每个人工创建的代码文件的开头都有文件头注释吗？

Question

我正在阅读All-In-One Code Framework Coding Standards文档,其中一个建议是在每个人工创建的代码文件的开头添加文件头注释.这是我第一次看到这样的推荐,对我而言,这只是一个不必要的丑陋的混乱,但我想知道是否有人可以解释为什么M $推荐这个？

他们的例子如下:

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

就个人而言,除非您有理由在您的代码中加入法律免责声明(例如,如果您将开源或将其与产品一起分发),我发现在每个源文件中都有一个共同的标题是有限的.有时,如果您包含来自第三方或开源项目的源代码,您可能有义务包含有关该代码的免责声明和原产地声明.

相反,我更喜欢使用C#XML代码注释,并将我的文档集中在类型和类上,而不是"模块"或代码文件.与类型(或方法或枚举等)一起生成的文档不太可能变得陈旧并提供更好的粒度.还有许多工具可以将这些注释转换为文档,或者使用它来提供智能感知支持.

从历史上看,这种做法起源于全球函数,常数和结构几乎可以存在于任何地方的语言; 并且通常会因组织或编译依赖性原因而共处一地.这些在托管/ .NET世界中几乎完全不相关.