C++ 如何以正确的方式编写代码注释和文档？这有什么标准吗？

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

例如，考虑下面的代码：

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);
}

---

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

< P> C++没有标准，比如JavaDoc，但是某些文档工具是流行的和常用的。在我的脑海里，我可以提到

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);

---

您可以格式化注释，以便以后生成文档。这方面最流行的工具是

，其他类似的工具可以提供帮助。基本上，您可以根据一些预定义的样式编写注释，并从HTML/PDF/等中提取文档。

您不想写太多。假设您为一个函数编写注释，这样将来可以节省您理解代码十分钟的时间。伟大的但是，假设你的评论太冗长，写下来要花五分钟，然后再花五分钟阅读。那你就没有时间了。不太好

---

你也不想写得太少。如果代码持续一两页而没有出现任何问题，那么，我希望代码像水晶一样清晰，否则您将浪费未来的时间

你不想用愚蠢的方式评论。当人们第一次开始写评论时，他们通常会变得兴奋，并写下如下内容：

// 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语句前面加上注释，“现在我们返回一个值”

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

在程序/功能之前用几句话说明它的功能

传递给它的值的描述

如果是函数，则说明其返回的内容

在过程/函数中，注释将代码拆分为较短的任务

对于看似棘手的代码块，请快速解释发生了什么

因此，我们需要一个描述在开始和几个路标内解释所采取的道路。这样做非常快，而且从长远来看可以节省大量时间

这是一个关于杀死坏外星人的理论的例子。考虑表示球员射击的子弹的物体。您经常需要调用一个函数来向上移动它，并查看它是否命中任何内容。我可能会这样编码：

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

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

---

引用自：

我讨厌迂腐（不，不是真的），但在这种情况下，最好的写作方式是删除所有3行评论，因为它们没有对读者说任何不明显的话。在这里同意jalf。此外，如果你想得到更多类似上述的好评论，请查看此。显示您的支持，并帮助它进入测试版。参考：这里是一个相当保守的说法。。。这个答案是链接文章中逐字给出的。只需添加链接并注释其相关性，即可保存一些虚拟树。以下几行内容：阅读这篇关于如何使代码更具可读性的文章，它有一个有趣的观点，即在技巧1下评论什么（不）。我不会投反对票，因为至少你提到了原文。@David，是的，我知道这是一份完全相同的副本，我想先分享链接。但那个页面有很多与这个问题无关的额外内容，所以我决定只复制相关文本。我理解你的观点，但我认为抄袭相关文本更好，所以我照做了。无论如何，谢谢你提到这一点：）我不确定你是否在回答这个问题。据我所知，问题更多的是关于文档（在源代码中键入注释）而不是注释。但是按照你的回答，你甚至可以把它推向更极端的观点：“注释”可以被认为是一种代码气味，表明代码不够清晰……我认为这是最常见的。有些人也喜欢添加类型。i、 e@PARAM STRING stringName这是一个字符串