Do have a file header comment at the start of every human-created code file?

Question

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.
\***************************************************************************/

Answer 1

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.

Answer 2

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.