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

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

/***************************模块头******************************\
模块名称：
项目：
版权所有（c）微软公司。
此源受Microsoft公共许可证的约束。
看见http://www.microsoft.com/opensource/licenses.mspx#Ms-PL。
保留所有其他权利。
本规范和信息按“原样”提供，不提供任何形式的担保，
明示或暗示，包括但不限于暗示
适销性和/或适用于特定用途的保证。
\***************************************************************************/

这不是一个不同寻常的建议。例如，Apache要求许可信息也包含在每个源代码文件中：

原因各不相同，但要对其进行合理讨论，请查看：

许多项目并不是对每个源文件都执行此策略，但在每个源文件的基础上遵守此策略的原因之一是（直接来自上面的讨论）：

“基本上，你所取得的只是一个较低的目标 人员意外违规的风险 您的许可证条款。您必须 决定这对你有多重要。”

--

---

我遵循这个标准，只是因为它让您第一眼就知道文件的作用。诚然，只有当编写标题的人努力编写一个好的描述时，这才是正确的，但我通常会这样做，并添加一个修改部分来记录文件的任何重大更改。

个人，除非您有理由在代码中添加法律免责声明（例如，如果您将开放源代码或将其与产品一起分发）我发现在每个源文件中有一个公共头的价值有限。偶尔，如果您包含来自第三方或开放源代码项目的源代码，您可能有义务包含关于该代码的免责声明和来源声明

相反，我更喜欢使用C#XML代码注释，并将文档重点放在类型和类上，而不是“模块”或代码文件。与类型（或方法或枚举等）共存的文档不太可能过时，并提供更好的粒度。还有许多工具可以将此类注释转换为文档，或使用它提供intellisense支持

---

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

这通常对开源项目、代码和应用程序非常有用les设计用于其他项目和其他人/公司等。它在封闭的企业环境中并不特别有用，比如说，在这种环境中，代码不会离开公司，团队总是一起工作，彼此了解，不一定有“项目”，而只是对核心产品进行不断的更改/增强，等等

---

与大多数推荐的这种性质的编码标准一样，这是一种判断要求。

这是为了满足法律要求而设计的

---

这没有任何技术用途。

您正在阅读Microsoft提供的源代码标准，这些源代码明确供公众使用，作为供人们查看和复制的示例。这种类型的代码通常会被拆分成单独的文件，因此每个文件中是否存在许可证信息非常重要

---

正如其他人所说，对于不希望公开的项目，通常不需要这样的标题。

我正在搜索一个工具，它可以自动将注释块插入到我的源文件中。但是，您刚刚结束了我的搜索。我确信……谢谢。@Omtara，您可能已经知道了这一点，因为这是非常重要的这是一篇很老的文章，但是c#有一个非常方便的库/分析器，名为stylecop，这将使您能够在intellisense和构建引擎的提示下添加文件头，以及向您的类型及其成员添加文档。