代码中的注释应该怎么说？

好的评论是不成文的评论。您应该努力以不需要注释的方式编写代码。

评论的问题在于

• 通常他们在一个地方，但他们需要在另一个地方被记住
• 编译器无法检查注释的有效性，因此当代码更改时，注释将过时

让我们来看看不需要注释的最常见情况。

1. 如果您想评论变量的用途，请删除评论，并将变量名称更改为更合适的名称。

   int n; // количество страусов
   

   更好地更换

   int numberOfOstriches;
   

2. 如果您想发出满足某些条件的信号，最好放置assert：

   // тут pBFG не может быть nullptr-ом, проверка не нужна
   pBFG->fire();
   

   更好地更换

   assert(pBFG);
   pBFG->fire();
   

3. 如果您在评论中描述了一段代码的确切作用，那么将这段代码分成一个单独的函数是有意义的，并将代码的重点作为它的名称。

   // нормализовать вектор скорости
   double temp_length = sqrt(velocity.x * velocity.x + velocity.y * velocity.y);
   velocity.x /= temp_length;
   velocity.y /= temp_length;
   

   更好地更换

   void Normalize(vector& v)
   {
       double length = sqrt(v.x * v.x + v.y * v.y);
       if (length == 0.0)
           throw argument_exception("zero length vector");
       v.x /= length;
       v.y /= length;
   }
   

   Normalize(velocity);
   

4. 如果你在评论中描述了不言而喻的事情，最好直接扔掉这条评论。

   // этот класс представляет точку
   class Point
   {
       public int X; // координата X
       public int Y; // координата Y
   }
   

   这种形式不会失去一点可读性：

   class Point
   {
       public int X;
       public int Y;
   }
   

   （如果编码标准要求您提供无意义的评论，请要求更改这些标准！）

因此，一段代码中发生的事情应该尽可能从代码本身清楚。如果不是，请改进它。

如果注释实际上是您代码的文档，那么您无能为力，您不需要删除它。

真正需要评论的几个地方是对所用算法的描述、优化、错误修复和非显而易见的解决方案的文档。在这里，再次尝试写下你为什么做你所做的事情。从代码中应该可以清楚地知道您是如何做到的。

“好吧，先生，设定任务”......（c）电影“爱情公式”

评论没有要求。你看，这就像问故事应该描述作者的意图还是人物的行为？制作本身很奇怪 - 在评论中究竟写了什么......并且区分“正在发生的事情”和“应该发生的事情”是完全奇怪的。

事实上，代码应该以这样一种方式编写，即它自己对它所做的事情进行评论。不是我发明的，但我大体上同意这一点。当然不需要本着“将其他两个的总和分配给一个变量”的精神发表评论:)

写评论，以便在一两年内您可以查看代码并弄清楚它的作用。

另外，我会强调关于你需要记住做什么的评论:)

如果你在团队中工作，那么按照团队的决定工作。

最后，引用 Sutter 的话：

不要规定评论的风格（除非一个特殊的工具包将它们用于文档），而只写相关和有用的评论。尽可能编写代码而不是注释。

代码中的良好注释 （而不是在函数之前等）应该解释为什么需要这篇文章来解决问题。

很可能为了理解这个“为什么”，有必要描述初始数据的状态以及注释代码执行后发生的情况。

以及具体是如何实现的，最好告诉代码本身。