Language agnostic 文件头或一般性评论

有人对一个文件有一个结构良好的开始注释吗？我在找一件好看的东西，要么很别致，要么很专业

我所说的一般性评论是指文件顶部的评论，显示您的姓名和文件的目的。像这个：

/********************************************************           
    * hello -- program to print out "Hello World".         *   
    *                                                      *   
    * Author:  FirstName, LastName                         *   
    *                                                      *   
    * Purpose:  Demonstration of a simple program.         *   
    *                                                      *   
    * Usage:                                               *   
    *      Runs the program and the message appears.       *   
    ********************************************************/  

格式

对于C#，强制执行如下所示的标题

// <copyright file="filename.cs" company="Company">
// Copyright (c) 2008 All Right Reserved
// </copyright>
// <author>Mr blah blah</author>
// <email>blahblah@blahblah.com</email>
// <date>2009-11-21</date>
// <summary>File description.</summary>

//
//版权所有（c）2008保留所有权利
// 
//诸如此类
// blahblah@blahblah.com
// 2009-11-21
//文件描述。

---

您可以在版权标签中配置所需的公司名称。

对于Java，我更喜欢以下样式（但这些要点也可以应用于其他语言）：

• 如果你想包括一些版权的东西，在第一行或第二行。保持简短。如果您对此有更多的想法，请在自述文件或产品的网站上进行

• 不要包含任何元信息，如文件名、上次修改日期、@author或@version标记。像Subversion这样的工具可以更好地跟踪这些事情，而复制此类信息只会增加不必要的工作以保持它们的同步

• 用一句话概括类的javadoc的主要功能

• 不需要使用像目的或用法这样的标题，只需在几段中解释你要说的话。如果脚本需要处理表单和字段，则表单和字段非常有用，但如果人们愿意阅读表单和字段，则表单和字段就不那么有用了

所以总结起来，我用了这样的方法：

/* Copyright 2002-2009 Foo Ltd. All rights reserved. */

package foo.bar;

/**
 * This class does this or that.
 *
 * Now you can go into the details, try to be professional here by writing a
 * few clear, articulate paragraphs, not by drawing fancy ascii boxes.
 *
 * @see foo.bar.OtherClass
 */
public class MyClass {
   ...
}

---

就我个人而言，我不喜欢这样的事情。我认为用星星勾勒出来的方框看起来像学生代码，只会增加视觉上的混乱。无论如何，解释一下javadocs中发生了什么。别把它弄得乱七八糟，我想你是对的。我真的不想添加太多东西，但我仍然想添加我的名字和一些基本信息+1达菲莫；它们很容易维护（这往往意味着它们没有被维护，并且与代码不同步）。使用一些简单的方法，使自动生成API文档变得简单（javadocs、doxygen等）。文件头注释很少不同步-文件的用途通常不会改变，作者也不会改变。这取决于你在标题中还包括了什么——用法可能会改变，但我不会把它放在“文件标题注释”中，而是放在靠近文件顶部的第二个注释中。一旦我创建了文件头，我就很少需要更改它。我的经验是，文件头注释经常会过时。对于大多数软件来说，“作者”是一个无用的概念；你想要的是“询问此代码的人”，这确实是很难维护的。我是唯一一个认为这看起来很难看的人吗？既然大多数人都要阅读原始源代码，为什么还要使用这些标记呢？如果你真的必须使用这样的系统，试试自然文档。

/* Copyright 2002-2009 Foo Ltd. All rights reserved. */

package foo.bar;

/**
 * This class does this or that.
 *
 * Now you can go into the details, try to be professional here by writing a
 * few clear, articulate paragraphs, not by drawing fancy ascii boxes.
 *
 * @see foo.bar.OtherClass
 */
public class MyClass {
   ...
}