c# - 每个人工创建的代码文件的开头是否都有文件头注释？

Question

我正在浏览 All-In-One Code Framework编码标准文档和其中一项建议是在每个人工创建的代码文件的开头添加文件头注释。这是我第一次看到这样的推荐，对我来说这只是一个不必要且丑陋的困惑，但我想知道是否有人可以解释为什么 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

就我个人而言，除非您有理由在您的代码中加入法律免责声明(例如，如果您将其开源或与产品一起分发)，我发现在每个源文件中使用通用 header 的值(value)有限. 有时，如果您包含来自第三方或开源项目的源代码，您可能有义务包含有关该代码的免责声明和来源声明。

相反，我更喜欢使用 C# XML 代码注释，并将我的文档重点放在类型和类上，而不是“模块”或代码文件上。与类型(或方法，或枚举等)不太可能变得陈旧并提供更好的粒度。还有许多工具可以将此类评论转换为文档，或使用它来提供智能感知支持。

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