Question

当我开始编写应用程序代码时，我并不十分谨慎地评论我的代码。后来我当然后悔了。这已经发生了很多次，我正在寻找一些关于如何有效地评论代码的技巧，我仍然理解我所写的内容。我不想像这样结束

 //When I wrote this code only my and god understood what it did... now only god do

Answer 1

解释算法何时从代码语义中不清楚（具有人类可读的变量和方法名称，最好是对它们进行评论!!）。
根据您的变量/参数/函数名称（例如int distance_in_meters;，int dist_cm;，int calc_dist_cm(point a, point b);）
解释接口及其行为（在课程级别）。
解释你必须实施的黑客攻击，以处理笨拙的第三方或操作系统界面。

代码中的其他所有内容都应该通过使用类的正确命名，（成员）变量/函数和标准算法的使用来表达。

示例：

// represents a point (x,y value) in a cartesian coordinate system
class point {
public:
    point(double x, double y);
    // Copy constructor for point
    point(const point& rhs);
    double x() const; // get x value
    void x(double value): // set x value
    double y() const; // get y value
    void y(double value): // set y value

    // Calculates the distance from an 'other' point in cartesian units
    double getDistance(const point& other) const;      
private:
    double x_;
    double y_;
}

Answer 2

记录为什么您决定使用某些设计。通常，在软件工程和编程中，有许多解决方案可以完成某项任务，重要的是要知道利弊的权衡，最终导致您决定使用解决方案X.

如果您的设计偏离了编程语言中已有的标准惯用语，或者您似乎重新实现了方向盘但是有充分的理由这样做（遗留系统，某个客户系统的极端条件，时间压力由于一些截止日期，与某些库或框架的兼容性等。）

Answer 3

不同的评论风格适合不同的场景和项目。语言随着时间而变化，评论风格也是如此。

要记住的第一件事是，评论只是众所周知的一件事，以保持人类可以理解的代码。在大公司和大型项目中，规格，测试计划等文件都是将胶带粘在一起的胶带。在许多现代脚本语言中，编码风格（命名约定，接口选择等）与您对代码片段的作用的评论同样重要。在某些语言中采用良好的编码风格几乎可以使代码自我解释。

我的第二个建议是在开始编码之前发表评论。这就像在开始绘画之前绘制草图一样，它可以帮助您阐明自己的意图。如果你能描述你想做什么以及你将如何用文字来表达，那么你肯定可以用代码来做。

最后，不要过度评论，让每个单词都有意义，对你和维护者都很好。

Answer 4

本书Clean Code描述了（在我看来）如何处理评论的好方法。

该部分的博士是：

喜欢重构方法/变量/类，以便描述他们正在做得更好
少即是多，如果评论太多，人们不太可能阅读它们
评论可能会过时，代码不会
作为最后的手段，写下评论来描述代码的意图

在您关于不知道自己在做什么的评论的特定示例中，您应该重构该代码。如果你甚至无法描述你编写的代码，那那肯定是错误的代码。好的评论不能弥补编写错误的代码。

Answer 5

我在自己的代码中写的评论很少。我依靠：

功能名称
变量的一致和好名称。
为“常量”使用枚举和其他符号名称。
使用类型声明来解释类型的用途。

请注意，“好名字”是语境。在一小段代码中重复多次的长复杂名称不一定比短名称更好。关键是名称应该是变量的一个很好的线索。调用变量outerLoopVariable并不比调用它i好多少。调用用于相同目的的参数，在不同但密切相关的函数上使用相同的名称绝对是个好主意。这样，你知道在下一个函数中它是一样的。

同样，尝试找出一段代码中1或17的原因有时并不是特别容易，如果它被称为NumberOfElements或{{1更有意义。

如果函数的参数在类型和名称上不明显，那么在函数之前可能需要一些注释来解释输入是什么，以及它们应该是什么。

类型对以下内容也很重要： 1.确保将正确的东西传递给函数。 2.再提一下“这件事做了什么”。

例如。 ColorGreen并不像char *buffer;那样清晰，尽管指向完全相同的类型，但后一版本解释了typedef char* PixelBuffer; PixelBuffer *buffer;实际上不是文本字符串，文件缓冲区或其他东西，但是包含像素的缓冲区。

另一个经常发现的“缺陷”是缺乏遵循“一个函数应该做一件事”的规则 - 如果你有一个功能可以做很多事情，那么很难确定函数是否可以被重用或者不。

坚持使用小功能通常是一个好主意，并且拥有许多功能。如果现代编译器认为它有用，那么它就会很好地进行内联（如果你不重复这些东西的话，很可能你会得到更高效的代码）。

Answer 6

依赖评论并不是一件好事，因为它会随着时间而腐烂。有效评论代码的更好方法是：

选择好名字（变量，方法，类）
在可能的情况下尽可能使用断言作为前后条件
使用单位测试。单元测试解释了方法的行为。
KISS保持简单愚蠢，干不要自己重复

有些人喜欢在代码中编写一些TODO或FIX。相反，我建议你使用失败的单元测试。请记住，您很少需要在代码中编写注释，并且应该尽量避免使用注释。

我建议您阅读清洁代码：敏捷软件工艺手册以获取更多信息。

好的代码评论提示

6 个答案: