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

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

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

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

Answer 2

这对于开源项目，设计用于其他项目和其他人/公司等的代码文件通常很有用。它在一个封闭的企业环境中并不是特别有用，在这种情况下代码不会离开公司，团队总是一起工作，彼此了解，不一定是“项目”，只是对核心产品的持续改变/增强等。

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

Answer 3

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

http://www.apache.org/legal/src-headers.html

原因各不相同，但为了对它们进行合理的讨论，请查看：

Putting license in each code file?

许多项目不会对每个源文件执行任何操作，但是基于每个源文件遵循此策略的原因之一是（直接来自上面关于SO的讨论）：

“基本上，你所取得的成就都是较低的   人们意外违反的风险   你的许可条款。你必须这样做   决定对你有多重要。“

- https://stackoverflow.com/users/16883/michael-borgwardt

Answer 4

我遵循该标准只是因为它让您了解文件在第一眼看到的内容。当然，如果编写标题的人努力编写一个好的描述，但我通常会这样做以及添加一个修改部分来记录文件的任何重大更改。

Answer 5

这旨在满足法律要求。

这不用于技术目的。

Answer 6

您正在阅读Microsoft明确公开提供的来源的编码标准，作为人们查看和复制的样本。将这种类型的代码拆分成单个文件是很常见的，因此每个文件中存在许可信息非常重要。

正如其他人所说的那样 - 对于预计不会公开的项目，通常不需要此类标题。

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

6 个答案: