代码中是否有标准的注释格式？

Question

我想知道人们的代码中是否有标准的评论格式.没有东西像一个方法或类XML注释,而是评论中的方法.

---

也可以看看:

是否有用于评论C#代码的标准(如phpdoc或python的docstring)？

Answer 1

除了格式化之外,你应该考虑做一些好的评论.

1. 不要简单地重述代码正在做什么.例如,

 // Start the services
 StartServices();

是一个可怕的评论!

2. 描述原因.为什么代码正在做它正在做的事情？什么是业务假设或算法步骤？

3. 格式化注释以获得最大可读性.正确地标记它们,在必要时留出空间等.

4. 如果某人已经开始以标准方式发表评论,请不要违反该标准.

5. 在MSDN上查看有关编写有效注释的文章:http: //msdn.microsoft.com/en-us/library/aa164797.aspx

Answer 2

// I usually write comments like this

在我工作的地方,需要对大多数声明(类,方法,一些属性)使用标准的xml注释样式(我们使用C#).

有时您可以看到正在使用的页眉/页脚注释.

/****************************************************/
// Filename: Customer.cpp
// Created: John Doe
// Change history:
// 18.12.2008 / John Doe
// 14.01.2009 / Sara Smith
/****************************************************/

/* Here goes a lot of stuff */

/****************************************************/
// EOF: Customer.cpp
/****************************************************/

在我的一个旧工作场所使用了类似的东西.在我看来,太多不必要的东西.如今,通过版本控制系统可以很好地看到变更历史.

在许多优秀的软件商店中,有关于何时以及如何撰写评论的内部指南.文档通常被称为"源代码样式策略"或其他东西.在评论代码时坚持一种共同的风格是非常重要的.

当然,这种评论炒作不应该过于评论每一小段代码,特别是明显的代码.

/// <summary>
///     Handles the standard PageLoad event
/// </summary>
/// <param name="sender">
///    Event sender
/// </param>
/// <param name="e">
///    Event arguments
/// </param>
public void Page_Load (object sender, EventArgs e)
{
    // Do something here
}

这是一个过度迷恋评论的好例子.像这样的东西只添加零信息,但只会增加源文件的噪音.我们必须按要求在工作中这样做.

我个人的意见是当你有话要说或解释时添加评论,而不仅仅是为了评论一切.

Answer 3

/**
 * block comments to document a method for javadoc go like this
 * @param
 * @return
 * @exception BTKException
 * @see BTK
 */