C语言的注释之美

注释

一般的,尽量通过清晰的架构逻辑,

好的符号命名来提高代码可读性;

需要的时候,才辅以注释说明。

注释是为了帮助阅读者快速读懂代码,

所以要从读者的角度出发,按需注释。

注释内容要简洁、明了、无二义性,信息全面且不冗余。

注释跟代码一样重要。

写注释时要换位思考,用注释去表达此时读者真正需要的信息。

在代码的功能、意图层次上进行注释,

即注释解释代码难以表达的意图,不要重复代码信息。

修改代码时,也要保证其相关注释的一致性。

只改代码,不改注释是一种不文明行为,

破坏了代码与注释的一致性,让阅读者迷惑、费解,甚至误解。

使用流利的中文或英文进行注释。

为降低沟通成本,应使用团队内最擅长、沟通效率最高的语言写注释;

注释语言由开发团队统一决定。

注释风格

在 C 代码中,使用 /* */和 // 都是可以的。

按注释的目的和位置,注释可分为不同的类型,

如文件头注释、函数头注释、代码注释等等;

同一类型的注释应该保持统一的风格。

注意:本文示例代码中,

大量使用 '//' 后置注释只是为了更精确的描述问题,

并不代表这种注释风格更好。

文件头注释

规则3.1 文件头注释必须包含版权许可和功能说明

文件头注释必须首先包含上述两项。

如果需要在文件头注释中增加其他内容,可以后面以相同格式补充。

比如:作者、创建日期、注意事项等等。

版权许可内容及格式必须如下,中文版:

版权所有 (c) XX技术有限公司 2012-2019

英文版:

Copyright (c) XX Technologies Co., Ltd. 2012-2019. All rights reserved.

关于版本说明,应注意:

2012-2020根据实际需要可以修改。

2012 是文件首次创建年份,而 2020是最后文件修改年份。

二者可以一样,如 "2020-2020"。

对文件有重大修改时,必须更新后面年份,

如特性扩展,重大重构等。

版权说明可以使用XX子公司。

如:版权所有 (c) XX-XX 2012-2020

或英文:Copyright (c) XX-XX Technologies Co., Ltd. 2012-2020. All rights reserved.

最简文件头注释举例:

增加包含了'Author', 'Create' 和 'Notes' 的文件头举例:

编写文件头注释应注意:

文件头注释必须从文件顶头开始。

如果包含"关键资产说明"类注释,则应紧随其后。

保持统一格式。

具体格式由项目或更大范围统一制定。格式可参考上面举例。

必须首先包含"版权许可"与"功能说明"。

其他选项按需添加,并保持格式统一。

禁止空有格式,无内容。

如上述例子,如果选项 'Notes' 后面无内容,则应整行删除。

若内容过长,超出行宽要求,换行时应注意对齐。

对齐可参考上述例子 'Notes'

函数头注释

规则3.2 禁止空有格式的函数头注释

并不是所有的函数都需要函数头注释;

函数签名无法表达的信息,加函数头注释辅助说明;

函数头注释统一放在函数声明或定义上方。

选择使用如下风格之一:

使用'//'写函数头

使用'/*' '*/' 写函数头

函数尽量通过函数名自注释,按需写函数头注释。

不要写无用、信息冗余的函数头;不要写空有格式的函数头。

函数头注释内容可选,但不限于:功能说明、返回值,性能约束、用法、内存约定、算法实现、可重入的要求等等。

模块对外头文件中的函数接口声明,其函数头注释,应当将重要、有用的信息表达清楚。

例:

坏的例子:

上面例子中的问题:

参数、返回值,空有格式没内容

函数名信息冗余

关键的 buf 由谁释放没有说清楚

代码注释

规则3.3 代码注释放于对应代码的上方或右边

规则3.4 注释符与注释内容间要有1空格;右置注释与前面代码至少1空格

代码上方的注释,应该保持对应代码一样的缩进。

选择并统一使用如下风格之一:

使用'//'

使用'/*' '*/'

代码右边的注释,与代码之间,至少留1空格,建议不超过4空格。

通常使用扩展后的 TAB 键即可实现 1-4 空格的缩进。

选择并统一使用如下风格之一:

右置格式在适当的时候,上下对齐会更美观。

对齐后的注释,离左边代码最近的那一行,保证1-4空格的间隔。

例:

当右置的注释超过行宽时,请考虑将注释置于代码上方。

规则3.5 不用的代码段直接删除,不要注释掉

被注释掉的代码,无法被正常维护;当企图恢复使用这段代码时,极有可能引入易被忽略的缺陷。

正确的做法是,不需要的代码直接删除掉。若再需要时,考虑移植或重写这段代码。

这里说的注释掉代码,包括用 /* */ 和 //,还包括 #if 0, #ifdef NEVER_DEFINED 等等。

建议3.1 正式交付给客户的代码不能包含 TODO/TBD/FIXME 注释

TODO/TBD 注释一般用来描述已知待改进、待补充的修改点

FIXME 注释一般用来描述已知缺陷

它们都应该有统一风格,方便文本搜索统一处理。如:

在版本开发阶段,可以使用此类注释用于突出标注;交付前应该全部处理并删除掉。

建议3.2 case语句块结束时如果不加break/return,需要有注释说明(fall-through)

有时候需要对多个case标签做相同的事情,case语句在结束不加break或return,直接执行下一个case标签中的语句,这在C语法中称之为"fall-through"。

这种情况下,需要在"fall-through"的地方加上注释,清晰明确的表达出这样做的意图;或者至少显式指明是 “fall-through”。

例,显式指明 fall-through:

如果 case 语句是空语句,则可以不用加注释特别说明:

  • 发表于:
  • 原文链接https://kuaibao.qq.com/s/20200403A0MKYD00?refer=cp_1026
  • 腾讯「云+社区」是腾讯内容开放平台帐号(企鹅号)传播渠道之一,根据《腾讯内容开放平台服务协议》转载发布内容。
  • 如有侵权,请联系 yunjia_community@tencent.com 删除。

扫码关注云+社区

领取腾讯云代金券