深入了解如何注释以及在哪儿注释

开课吧小一2021-06-11 17:42

点赞
有用
分享分享

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

深入了解C++如何注释以及在哪儿注释

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

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

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

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

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

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

深入了解C++如何注释以及在哪儿注释

    弃用注释:通过弃用注释(DEPRECATED comments)以标记某接口点(interfacepoints)已弃用。

    您可以写上包含全大写的 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.

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

    以上就是小编为大家整理的“深入了解C++如何注释以及在哪儿注释”一文,更多相关信息尽在开课吧C/C++教程频道。

相关推荐:

2021大厂高频面试题精选,0元免费领

福利来袭,C++经典项目实战免费领取!

职场进阶必备,数据分析职业能力特训营

免责声明:本站所提供的内容均来源于网友提供或网络搜集,由本站编辑整理,仅供个人研究、交流学习使用。如涉及版权问题,请联系本站管理员予以更改或删除。
有用
分享