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

新书介绍

《实战Python设计模式》是作者最近出版的新书，拜托多多关注！

本书利用Python 的标准GUI 工具包tkinter，通过可执行的示例对23 个设计模式逐个进行说明。这样一方面可以使读者了解真实的软件开发工作中每个设计模式的运用场景和想要解决的问题；另一方面通过对这些问题的解决过程进行说明，让读者明白在编写代码时如何判断使用设计模式的利弊，并合理运用设计模式。

对设计模式感兴趣而且希望随学随用的读者通过本书可以快速跨越从理解到运用的门槛；希望学习Python GUI 编程的读者可以将本书中的示例作为设计和开发的参考；使用Python 语言进行图像分析、数据处理工作的读者可以直接以本书中的示例为基础，迅速构建自己的系统架构。

---

觉得本文有帮助？请分享给更多人。

关注微信公众号【面向对象思考】轻松学习每一天！

面向对象开发，面向对象思考！