深入了解C++如何注释以及在哪儿注释-开课吧广场

注释虽然写起来很痛苦，但对保证代码可读性至关重要，同时这也是每一个C++开发工程师所需要做好的事情。那么C++开发过程中该如何注释？应该在哪写注释呢？

关于注释风格，很多C++的Coders更喜欢行注释，Ccoders或许对块注释依然情有独钟，或者在文件头大段大段的注释时使用块注释；

文件注释可以炫耀你的成就，也是为了捅了篓子别人可以找你;

注释要言简意赅，不要拖沓冗余，复杂的东西简单化和简单的东西复杂化都是要被鄙视的;

对于Chinesecoders来说，用英文注释还是用中文注释，it is a problem，“但不管怎样，注释是为了让别人看懂，难道是为了炫耀编程语言之外的你的母语或外语水平吗；

注释不要太乱，适当的缩进才会让人乐意看.但也没有必要规定注释从第几列开始(我自己写代码的时候总喜欢这样)，UNIX/LINUX下还可以约定是使用Tab还是Space，个人倾向于space;

TODO很不错，有时候，注释确实是为了标记一些未完成的或完成的不尽如人意的地方，这样一搜索，就知道还有哪些活要干，日志都省了。

弃用注释：通过弃用注释（DEPRECATED comments）以标记某接口点（interface points）已弃用。

您可以写上包含全大写的 DEPRECATED 的注释，以标记某接口为弃用状态。注释可以放在接口声明前，或者同一行。

在 DEPRECATED 一词后，留下您的名字，邮箱地址以及括号补充。

仅仅标记接口为 DEPRECATED 并不会让大家不约而同地弃用，您还得亲自主动修正调用点（callsites），或是找个帮手。

修正好的代码应该不会再涉及弃用接口点了，着实改用新接口点。如果您不知从何下手，可以找标记弃用注释的当事人一起商量。

TODO注释。对那些临时的, 短期的解决方案，或已经够好但仍不完美的代码使用TODO注释.

TODO注释要使用全大写的字符串TODO，在随后的圆括号里写上你的大名, 邮件地址, 或其它身份标识，冒号是可选的。主要目的是让添加注释的人 (也是可以请求提供更多细节的人) 可根据规范的TODO格式进行查找。添加TODO注释并不意味着你要自己来修正。

标点, 拼写和语法

注意标点，拼写和语法；写得好的注释比差的要易读的多。

注释的通常写法是包含正确大小写和结尾句号的完整语句。短一点的注释（如代码行尾注释）可以随意点，依然要注意风格的一致性。完整的语句可读性更好，也可以说明该注释是完整的，而不是一些不成熟的想法。

虽然被别人指出该用分号时却用了逗号多少有些尴尬，但清晰易读的代码还是很重要的。正确的标点，拼写和语法对此会有所帮助。

实现注释：

对于代码中巧妙的, 晦涩的, 有趣的, 重要的地方加以注释。

代码前注释:

巧妙或复杂的代码段前要加注释。比如：

// Divide result by two, taking into account that x
// contains the carry from the add.
for (int i = 0; i < result->size(); i++) {
    x = (x << 8) + (*result)[i];
    (*result)[i] = x >> 1;
    x &= 1;
}

行注释：

比较隐晦的地方要在行尾加入注释。在行尾空两格进行注释。比如：

// If we have enough memory, mmap the data portion too.
mmap_budget = max<int64>(0, mmap_budget - index_->length());
if (mmap_budget >= data_size_ && !MmapData(mmap_chunk_bytes, mlock))
    return;  // Error already logged.

注意，这里用了两段注释分别描述这段代码的作用，和提示函数返回时错误已经被记入日志。