如何以正确的方式编写代码内注释和文档？这有啥标准吗？ [关闭]

Posted 2023-02-21

【中文标题】如何以正确的方式编写代码内注释和文档？这有啥标准吗？ [关闭]

【英文标题】：How do I write in-code comments and documentation in a proper way? Is there any standard for this? [closed]如何以正确的方式编写代码内注释和文档？这有什么标准吗？ [关闭]

【发布时间】：2011-06-03 08:26:51

【问题描述】：

我想通过注释行在我的代码中添加文档。 这有什么标准格式吗？

例如，考虑下面的代码：

class Arithmetic

    // This method adds two numbers, and returns the result.
    // dbNum1 is the first number to add, and dbNum2 is second.
    // The returning value is dbNum1+dbNum2.
    static double AddTwoNumbers(double dbNum1, double dbNum2);

对于这个示例代码，有没有更好的方法来编写注释行？

【问题讨论】：

我讨厌学究气（不，不是真的），但在这种情况下，最好的编写方法是删除所有 3 行 cmets，因为他们没有说任何不明显的内容给读者。

在这里同意 jalf。此外，如果您想获得更多像上面这样的优秀 cmets，请查看 stack-exchange proposal。表达您的支持并帮助它进入测试阶段。

【参考方案1】：

对于 c++，没有像 javadoc 这样的标准，但某些文档工具很流行并且很常用。在我的脑海中，我可以提到doxygen。

Doxygen 也支持熟悉的 javadoc 风格，即：

/**
   This method adds two numbers, and returns the result.
   @param dbNum1 is the first number to add
   @param dbNum2 is second.
   @return The returning value is dbNum1+dbNum2.
*/
static double AddTwoNumbers(double dbNum1, double dbNum2);

【讨论】：

我会说这是最常见的。有些人也喜欢添加类型。即@PARAM STRING stringName 这是一个字符串

【参考方案2】：

您可以格式化您的 cmets，以便以后生成文档。最流行的工具是DoxyGen

【参考方案3】：

你不想写太多。假设您为一个函数编写 cmets，该函数将来可以为您节省 10 分钟理解代码的时间。伟大的。但是假设您的 cmets 非常冗长，以至于需要 5 分钟来编写它们，然后再用 5 分钟来阅读它们。然后，您节省了零时间。不太好。

你也不想写得太少。如果代码持续一两页而没有破坏正在发生的事情，那么我希望代码清晰如水晶，否则你就是在浪费未来的时间。

而且您不想以愚蠢的方式发表评论。当人们第一次开始编写 cmets 时，他们通常会很兴奋并写出如下内容：

// Now we increase Number_aliens_on_screen by one.
Number_aliens_on_screen = Number_aliens_on_screen + 1;

嗯嗯，呵呵。如果某件事如此明显，则不需要评论。而且，如果您的代码如此混乱，以至于您需要为每一行添加注释，那么您可能会从首先以其他方式简化代码中获益。评论不仅可以节省时间，而且还需要花费时间。它们需要时间阅读，并将实际代码分散在屏幕上，因此您可以在显示器上一次性检查更少的代码。

而且，当我们这样做的时候，永远不要这样做：

Short get_current_score()

    [insert a whole bunch of code here.]

    return [some value];

    // Now we're done.

哦？我们完了？谢谢你让我知道。那个大的右括号和无限广阔的空白空间真的并没有让我知道这一点。您也不需要在 return 语句之前添加注释，说“现在我们返回一个值”。

那么，如果你正在编写代码，在没有老板或公司政策告诉你该怎么做的情况下，你如何评论它？好吧，我为自己维护自己的代码所做的就是写一个介绍。当我回到一个我忘记了我写的程序时，我想看到一个关于正在发生的事情的解释。一旦我理解了机器在做什么，理解实际编码就会变得非常容易。这通常涉及：

在过程/函数之前的几句话说明它的作用。 传递给它的值的描述。 如果是函数，则说明它返回的内容。 在过程/函数内部，cmets 将代码拆分为更短的任务。 对于看起来很棘手的代码块，快速解释发生了什么。

因此，我们需要在开头进行描述，并在里面设置一些路标来解释所走的路。这样做非常快，从长远来看可以节省大量时间。

这是理论上的杀死坏外星人的一个例子。考虑代表玩家发射的子弹的对象。你经常需要调用一个函数来向上移动它，看看它是否碰到任何东西。我可能会这样编码：

// This procedure moves the bullet upwards. It's called
//NUM_BULLET_MOVES_PER_SECOND times per second. It returns TRUE if the
//bullet is to be erased (because it hit a target or the top of the screen) and FALSE
//otherwise.
Boolean player_bullet::move_it()

    Boolean is_destroyed = FALSE;

    // Calculate the bullet's new position.

    [Small chunk of code.]

    // See if an enemy is in the new position. If so, call enemy destruction call and
    // set is_destroyed to TRUE

    [small chunk of code]

    // See if bullet hits top of screen. If so, set is_destroyed to TRUE

    [Small chunk of code.]

    // Change bullet's position.

    [Small chunk of code.]

    Return is_destroyed;

如果代码足够干净，这种注释就足够了。在我返回这个函数来修复我犯的一个愚蠢的错误时，它会节省大量时间。

引用自：here

【讨论】：

Referred from: here 相当轻描淡写……这个答案是链接文章中逐字逐句的。您可以通过添加链接并评论其相关性来保存一些虚拟树。内容如下：阅读这篇关于如何使代码更具可读性的文章，它有一个有趣的观点，即在提示 1 下什么（不）要评论。 我不会投反对票，就像在至少您确实参考了原始文章。

@David，是的，我知道它是一个精确的副本，我想先分享链接。但是那个页面有很多与这个问题无关的额外内容，所以我决定只复制相关的文本。我理解你的意思，但我认为复制相关文本更好，所以我做了。无论如何，感谢您提及:)

我不确定您是否回答了这个问题。据我了解，问题更多的是关于文档（在源代码中作为评论输入）而不是评论。但是根据您的回答，您甚至可以将其推向更极端的观点：“cmets”可以被视为代码气味，表明代码不够清晰....memeagora.blogspot.com/2008/11/comments-code-smell.html

【参考方案4】：

Doxygen 和其他类似的工具可以帮助解决这个问题。基本上你根据一些预定义的样式和 HTML/PDF/etc 编写 cmets。文档已提取。