I'm going through All-In-One Code Framework Coding Standards document and one of the recommendations is to add a file header comment at the start of every human-created code file. This is the first time I've seen such a recommendation and to me it's just an unnecessary and ugly clutter but I'm wondering if someone could explain why M$ recommends this?
Their example looks like this:
/****************************** Module Header ******************************\
Module Name: <File Name>
Project: <Sample Name>
Copyright (c) Microsoft Corporation.
<Description of the file>
This source is subject to the Microsoft Public License.
See http://www.microsoft.com/opensource/licenses.mspx#Ms-PL.
All other rights reserved.
THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.
\***************************************************************************/
Personally, unless you have a reason to put a legal disclaimer in your code (such as if you will open source it or distribute it with a product) I find limited value in having a common header in each source file. Occasionally, if you include source code from a third-party or from an open source project, you may be obligated to include a disclaimer and statement of origin about that code.
Instead, I prefer to use C# XML code comments, and focus my documentation on types and classes, rather than "modules" or code files. Documentation that lives together with a type (or method, or enum, etc) is less likely to become stale and provides better granularity. There are also many tools that can convert such comments into documentation and or use it to provide intellisense support.
Historically, this practice originated with languages where global functions, constants, and structs could live almost anywhere; and often would be co-located either for organizational or compilational dependency reasons. These are almost entirely irrelevant in the managed/.NET world.
This is often useful for open-source projects, code files designed to be re-used in other projects and by other people/companies, etc. It's not particularly useful in, say, a closed enterprise environment where code doesn't leave the company, the team always works together and knows each other, there aren't necessarily "projects" but just ongoing changes/enhancements to a core product, etc.
As with most recommended coding standards of this nature, it's a judgement call.
This is not an unusual suggestion. Apache, for example, requires licensing info to be in every source code file as well:
http://www.apache.org/legal/src-headers.html
The reasons for this vary, but for a reasonable discussion of them, check out:
Putting license in each code file?
Many projects do NOT do every source file, but one of the reasons for obeying this policy on a per-source file basis is (directly from the above discussion on SO):
"Basically, all you achieve is a lower
risk of people accidentally violating
your license terms. You'll have to
decide how important that is to you."
-- https://stackoverflow.com/users/16883/michael-borgwardt
I follow that standard just because it gives you an idea of what the file does upon first glance. Granted this is only true if the person writing the header put the effort into writing a good description but I generally do this as well as adding a modificiations section to note any major changes to the file as well.
This is designed to satisfy legal requirements.
This serves no technical purpose.
You are reading coding standard for sources provided by Microsoft explicitly for public consumption as samples for people to look at and copy. It is common and expected for such type of code to be teared apart into individual files, so presences of license information in each file is important.
As everyone else is saying - for projects that are not expected to be public such headers are generally not needed.
