NL.1:请不要在注释中说明代码可以清楚表达的内容
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
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 ...
}
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