Question

如何保持源代码的良好记录/评论？是否有工具为Unix平台上的C ++生成注释骨架？

一般来说，对于包含大约100行代码的文件，建议使用多少行注释？

Answer 1

一般来说，最好让代码本身解释它的作用，而评论则用来描述为什么就是这样。没有数字可以坚持。如果您的100行代表自己说话，请不要发表评论或只是在开头提供摘要。如果涉及的某些知识超出了代码的范围，请在评论中解释。

如果您的代码太复杂而无法解释，那么这可能是重构的原因。

这样，当您更改实现时，您也不需要更改注释，因为您的注释不会复制代码。由于设计的原因很少改变，因此为了清晰起见，在评论中记录它们是安全的。

Answer 2

我个人认为骷髅评论是一个可怕的，可怕的想法。我知道有时候保存几次按键并且可能在评论中得到参数签名是很好的...但是产生n + 1个空无用的评论（当编辑器添加了样板并且编码器已经将它们保留原样时）更加令人恼火。

我确实认为无论如何都需要评论 - 如果只有代码一次编写对于解释来说太过微不足道，那么代码的可能性是无用的（即可能是自动化的，不需要手写）。我倾向于合理地评论我的代码，因为我已经知道通常我自己首先需要它。其他人可以使用它们只是一个额外的好处。

Answer 3

一般来说，对于包含大约100行代码的文件，建议使用多少行注释？

足以明确你的意图并解释所使用的任何不熟悉的习语。没有经验法则，因为没有两行代码是相同的。

例如，在C＃中，可以为属性提供如下的setter和getter：

public int ID { get; set; }

在我两周前加入StackOverflow之前，我甚至都没有看过任何C＃，但即使对我来说也不需要评论。用

// accessor and setter for ID property

只会是噪音。类似地，

for( int i = m ; i < n; ++i) { // "loop from m to n" is a pointless comment

char* p = getP() ; // set p to getP, pure noise.
if( p  ) // if p does not eqaul null, pure noise

int a &= 0x3; // a is bitwise or'd with 0x303, pure noise
              //  mask off all but two least significant bits, 
              //less noisy but still bad
              // get remainder of a / 4, finally a useful comment

同样，任何有能力的编码员都可以阅读代码，看看它在做什么。任何具有基本经验的编码员都知道if( p )是if( p != 0)的常用习语，不需要解释。但除非你发表评论，否则没有人可以阅读你的意图。

评论你要做的事情，你做这件事的原因，而不是代码显然在做什么。

在编辑时：您会注意到，在11天之后，没有人在我的一个示例评论中评论故意错误。这只是强调该评论是纯粹的噪音。

Answer 4

我认为这个问题对于类似的问题有很多很好的相关答案：Self-documenting code

至于创建评论的工具，取决于您使用的编辑器和平台。 Visual Studio会自动为注释创建空间，至少它有时会为C＃创建。还有一些工具使用注释来生成文档。至于行数，我认为这是无关紧要的。尽可能简洁明了。

Answer 5

我认为一个好的指导方针是对每个类和方法进行评论，并对每个类的方法进行一般性描述，特别是如果您使用的是HTML文档生成工具。除此之外，我尝试将评论保持在最低限度 - 只有可能令人困惑的评论代码，或者需要解释意图。尝试以不需要注释的方式编写代码。

我认为实际上没有一个度量标准可以应用于注释/代码行，它只取决于代码。

Answer 6

我个人的理想是写出足够的评论，以便只阅读评论解释了如何以及为什么要使用某个功能。它的工作原理通常应该来自精心选择的变量名称和明确的实现。

至少在评论方面，实现这一目标的一种方法是从一开始就使用Doxygen之类的工具。通过编写描述它的用途以及如何使用它的注释来开始编写每个新函数。

正确配置Doxygen，将文档生成包含在构建步骤中，并阅读生成的文档。

唯一可能有用的评论模板是在Doxygen评论块的最底层开始绘制的模板，但即使这样也可能太多了。您希望生成的文档能够解释什么是重要的，而不会使用永远不会重写的无用占位符文本使其混乱。

Answer 7

这是一个可以走极端的主题（如今很多事情）。恕我直言，执行强有力的政策有时可能会使这项工作贬值（即评论评论）。

有时，超越策略是有意义的（例如“所有公共函数必须具有注释块”），但有例外 - 为什么要生成代码呢？

评论应该是自然而然的 - 应该补充可读代码以及有意义的变量，属性和函数名称（等）。

我不认为每Y行代码有一个有用或准确的X注释测量。您可能会通过同行评审获得良好的平衡感（例如，“此处的代码应该有解释其目的的评论”）。

我不确定C / C ++的自动评论工具，但.Net等效工具必须是GhostDoc。同样，这些工具仅帮助定义注释结构 - 意味着仍需要由开发人员或必须解释代码或设计点的人员添加。

Answer 8

如果您自动生成文档（我们使用doxygen），则评论代码至关重要。否则最好将其保持在最低限度。

我们在.cpp文件中为每个方法使用一个骨架。

//**************************************************************************************************
//
/// @brief 
/// @details
/// @param  
/// @return
/// @sa 
//
//**************************************************************************************************

但这纯粹是出于我们的文档需求

Answer 9

我试图遵循的规则：

编写自动记录的代码：漂亮而清晰的变量名称，抵制聪明的黑客等诱惑。这个建议取决于很多关于你使用的编程语言：它更容易遵循Python而不是C。
在开头评论指导读者，让他们知道他们会立即得到什么。
评论代码中不明显的内容。如果你遇到麻烦写一段代码，可能意味着它应该发表评论。
图书馆的API是一个特例：需要文档（并将其放入代码中通常是一个好主意，特别是像Doxygen这样的工具。做就是了不要将用于用户的本文档与该文档混淆这对图书馆的维护者很有用。
评论代码中不能包含的内容，例如政策要求解释为什么事情就是这样。
评论背景信息这样的科学参考描述您使用的聪明算法或RFC的文章标准化您实施的网络协议。
评论黑客行为！每个人有时被迫使用黑客或解决方法，但对未来的维护者很好，评论它。读 “Technical debt”。

不要评论其余部分。定量规则，如“20％的线条必须是评论“明显是愚蠢的，显然只是为了的PHB。

Answer 10

我更喜欢用评论来解释

类\函数的目的是什么，
不应该做什么，
我做的任何假设都是类\ function的用户应该遵守的。

对于vi编辑器的用户，以下插件非常有用。我们可以为类注释，函数注释等定义模板。

csupport plug in

Answer 11

评论/代码比率方面没有好的规则。这完全取决于代码的复杂性。

我遵循一条（且只有一条）关于评论的规则（我希望保持灵活性）。

代码显示了事情是如何完成的，评论显示了已完成的工作。

有些代码根本不需要注释，因为它很明显：这通常可以通过使用好的变量名来实现。大多数情况下，我会评论一个函数，然后用函数注释主要块。

我认为这很糟糕：

// Process list by running through the whole list,
// processing each node within the list.
//
void processList (tNode *s) {
    while (s != NULL) {         // Run until reached end of list.
        processNode (s);        // Process the node.
        s = s->nxt;             // Move to next node.
    }
 }

因为你所做的只是编写代码三次。我更喜欢这样的东西：

// Process list (or rest of list if you pass a non-start node).
//
void processList (tNode *currentNode) {
    // Run through the list, processing each node.

    while (currentNode != NULL) {
        processNode (currentNode);
        currentNode = currentNode->nextNode;
    }
 }

Answer 12

我不知道有任何工具，但我觉得如果将来要由其他人维护，在代码中有一些注释总是好的。至少，为类和方法提供头部块是很好的，详细说明了类的含义以及方法的作用。但是，最好尽可能减少评论。

Answer 13

你们可能会争论，但我真的相信它：

通常，您不必撰写评论。就这样。代码必须以解释本身的方式编写，如果它不解释自己而你必须写评论，那么就会出错。

但是有一些例外情况：

你必须写一些非常神秘的东西来获得性能。所以在这里你可能需要写一些解释。
您向其他团体/公司提供图书馆，最好记录其API。
您的组织中有太多的新手程序员。

Answer 14

对于像上面的某些人那样编程错误的代码，也不会说你不需要它们，我不会那么粗鲁。

这还取决于您的编辑器以及您如何查看其中的代码，以及您希望其他人如何执行此操作。

例如，我喜欢用C＃创建区域。区域被命名为可折叠的代码区域，在某种程度上被称为代码容器。这样，当我看到编辑器时，我实际上看的是伪代码。

#region Connect to the database
   // ....
#endregion

#region  Prepare tables

   #region Cache tables ...

   #endregion


   #region Fix column names ...

   #endregion

#endregion

这种代码比我知道的任何其他代码更具可读性，但是当然，它需要编辑器支持使用名称自定义折叠。（如Visual Studio编辑器，VIM ......）。如果你将区域放入过程中，有人会说你可以达到相似的效果，但首先，你不能总是这样做，其次，你必须跳转到程序才能看到它的代码。如果您只是设置hotkies来打开/折叠该区域，您可以在滚动和阅读文本时快速查看其中的代码，并且通常可以快速移动到区域的层次结构中。

关于行注释，编写autodocuments本身的代码会很好，但不幸的是，这通常不能说。这个过程取决于项目，领域及其复杂性。

作为最后一点，我完全建议通过可移植和语言独立工具提供代码内文档，例如可以使其工作的NaturalDocs使用任何语言，不包含XML或任何特殊格式的自然语法（因此名称）加上它不需要安装多次。

如果有一个人不喜欢评论，他总是可以使用一些简单的工具删除它们。我甚至在我的编辑器中集成了这样的工具，并通过简单的菜单点击消除了评论因此，注释不能以任何无法快速修复的方式损害代码。

Answer 15

我说通常评论是难闻的气味。但内联代码文档很棒。我在robowiki.net：

详细阐述了这个主题

Why Comments are Bad

Answer 16

我同意每个人关于自我记录代码的看法。我还同意在文档生成方面需要特别注释。每个方法/类顶部的简短注释很有用，特别是如果您的IDE可以在代码完成中使用它来处理工具提示（如Visual Studio）。

我在这里没有提到的评论的另一个原因是类型不安全的语言，如JavaScript或PHP。您可以通过这种方式指定数据类型，尽管匈牙利语符号也可以帮助那些（我认为这是使用它的一种罕见情况）。

此外，像PHPLint这样的工具可以使用一些与类型相关的特殊注释来检查代码的类型安全性。

Answer 17

没有可以明智地用于评论的指标。你永远不应该说x行代码必须有y个注释，因为那样你最终会得到简单重用代码的无用的注释，这些会降低代码的质量。

100行代码的评论应尽可能少。

就个人而言，过去曾经使用它们，我不会使用像doxygen这样的东西来记录每个函数和每个需要标记描述的参数的内部代码，因为有了很好的代码，你有很多函数和良好的名字，大多数情况下，这些标记的描述不会说参数名称本身。

Answer 18

我的观点 - 源代码中的评论是邪恶的。代码应该是自我记录的。开发人员通常会忘记阅读和更新它们悲伤的Martin Fowler：“如果你需要对行块进行注释 - 只需要创建新功能”（这不是引用 - 这句话就像我记得的那样）。

最好保留实用程序模块的分离文档，项目的基本原则，库的组织，一些算法和设计思路。

几乎忘了：我曾经使用过代码注释。这是MFC / COM - 项目，我从MSDN howto文章中留下了非平凡解决方案/解决方法附近的链接。

100行源代码 - 如果不是，应该是可以理解的 - 它应该在少数函数上分离或重新组织 - 这将更容易理解。

是否有生成骨架的工具对于Unix平台上的评论 C ++？

如果你真的需要，Vim有插入doxygen评论模板的插件。

Answer 19

应始终在需要时记录源代码。人们争论什么和什么不记录。但是我想再说一遍。

假设我已经实现了一个返回a / b

的方法

因此，作为程序员，我是一个伟大的公民，我会暗示用户期待什么。

/**
 * Will return 0 if b is 0, to prevent the world from exploding.
 */
float divide(float a, float b) {
    if (b == 0) return 0;
    return a/b;
}

我知道，很明显，没有人会创建这样的方法。但这可以反映到其他问题，API的用户无法弄清楚函数的期望。

源代码中的评论

19 个答案: