确实有在每个人创建的代码文件开始的文件头评论？ [英] Do have a file header comment at the start of every human-created code file?

问题描述

我经历全在一站式示例代码库编码标准文件和提出的建议之一是添加一个文件头在每个人创建的代码文件的开头发表评论。这是我第一次见过这样的建议，对我来说只是一个不必要的和丑陋的混乱，但我想知道，如果有人可以解释为什么M $建议呢？

他们的例子是这样的：

  / ***************** *************模块头****************************** \ 
模块名称：<档案名称> 
类项目：<样品名称> 
版权所有（c）Microsoft公司。 
 
<保证文件的说明> 
 
这个源是受微软公共许可证。 
见http://www.microsoft.com/opensource/licenses.mspx#Ms-PL。 
其他所有权利保留。 
 
此代码，提供的信息按原状无任何形式的担保，
明示或默示的担保，包括但不限于适销性和/或使用的隐含
担保适合特定用途的保证。 
 \ ******************************************** ************ / 
  

解决方案

就个人而言，除非你有一个理由去投入一个法律声明在你的代码（例如，如果你将开源其或分发它的产品），我觉得在具有每一个源文件公共头价值有限。有时候，如果从第三方或者从一个开源项目，包括源代码，你可能有义务包括免责声明和产地有关代码的声明。

相反，我更喜欢使用C＃的XML代码注释，并注重我的类型和类的文档，而不是模块或代码文件。文档某一类型（或方法，或枚举等）住在一起不太可能变得陈旧，并提供更好的粒度。也有许多工具可以这样的评论转化成文件和或者用它来提供IntelliSense支持。

从历史上看，这种做法源于语言的地方全局函数，常量和结构可以住在任何地方;和经常将共同位于无论是对组织或compilational依赖性的原因。这些是管理/ .NET世界几乎完全不相干的。

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

解决方案

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.

这篇关于确实有在每个人创建的代码文件开始的文件头评论？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！