C++核心准则​：注释风格

NL.1: Don't say in comments what can be clearly stated in code

NL.1：请不要在注释中说明代码可以清楚表达的内容

Reason（原因）

Compilers do not read comments. Comments are less precise than code. Comments are not updated as consistently as code.

编译器不阅读注释。注释不如代码精确。注释不会一直随代码一起更新。

Example, bad（反面示例）

auto x = m * v1 + vv;   // multiply m with v1 and add the result to vv

Enforcement（实施建议）

Build an AI program that interprets colloquial English text and see if what is said could be better expressed in C++.

建立一个可以解释口语英语文本的AI程序，看看是否可以用C ++更好地表达。

NL.2: State intent in comments

NL.2: 在注释中说明意图

Reason（原因）

Code says what is done, not what is supposed to be done. Often intent can be stated more clearly and concisely than the implementation.

代码说明做了什么，而不会说明应该做什么。通常意图得表达可以比实现更清楚，更简明。

Example（示例）

void stable_sort(Sortable& c)
    // sort c in the order determined by <, keep equal elements (as defined by ==) in
    // their original relative order
{
    // ... quite a few lines of non-trivial code ...
}

Note（注意）

If the comment and the code disagree, both are likely to be wrong.

如果注释和代码相矛盾，则两者可能都是错误的。

NL.3: Keep comments crisp

NL.3：保持注释清晰

Reason（原因）

Verbosity slows down understanding and makes the code harder to read by spreading it around in the source file.

过于详细的注释减慢代码的理解速度，这种注释在源文件中四处传播会使代码难以阅读。

Note（注意）

Use intelligible English. I might be fluent in Danish, but most programmers are not; the maintainers of my code might not be. Avoid SMS lingo and watch your grammar, punctuation, and capitalization. Aim for professionalism, not "cool."

使用可理解的英语。我可能会说流利的丹麦语，但大多数程序员不是。我的代码的维护者可能不是。避免使用SMS术语，并注意语法，标点和大写字母。追求专业，而不是“酷”。

Enforcement（实施建议）

not possible.

原文链接

https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#nl-naming-and-layout-rules