Question

有没有人对文件有一个很好的结构良好的起始评论？我正在寻找看起来不错的东西，无论是花哨的还是非常专业的。

一般性评论是指文件顶部的注释，显示您的文件名称和用途。像这样：

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

Answer 1

doxygen格式？

/*! \file hello.cpp
\brief program to print out "Hello World"

Created: 2009-11-21 by FirstName, LastName \n
Modified: \n
*/

Answer 2

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

如果您想要包含一些版权内容，请在前一行或两行中进行。保持简短。如果您对此有更多的话要说，请在某些README文件或产品的网站上进行。
不要包含任何元信息，例如文件名，最后修改日期，@ 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 {
   ...
}

Answer 3

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

// <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>

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

文件标题或一般注释

3 个答案: