给代码写注释时有哪些讲究?
良许Linux
共 2626字,需浏览 6分钟
·
2021-02-02 07:45
整理/来源:strongerHuang
如果领导给你一个项目的源码让你阅读,并理解重构代码,但里面一句注释都没有,我想这肯定是之前同事“删库跑路”了。
一般使用 //
或 /* */
,只要统一就好。
2. 说明
//
或 /* */
都可以,但团队要在如何注释及注释风格上确保统一。
2. 说明
3. 文件内容
如果一个 .h
文件声明了多个概念, 则文件注释应当对文件的内容做一个大致的说明, 同时说明各概念之间的联系。一个一到两行的文件注释就足够了, 对于每个概念的详细文档应当放在各个概念中, 而不是文件注释中。
不要在 .h
和 .cc
之间复制注释, 这样的注释偏离了注释的实际意义。
最后再举个最简单的实际例子:
/************************************************************************
*
* Copyright Copyright 2020 Google Inc.
* File Name: 文件名
* Description: 描述
*
* Version: V1.0
* Author: Your_Name
* Create Time: 2020-01-01
*
*************************************************************************/
2. 说明
比如:
/************************************************************************
*
* 函 数 名:函数名
* 函数功能:功能描述
* 输入参数:void
* 输出参数:void
* 返 回 值: void
*
* 作 者:Your_Name
* 创建时间:2020-01-01
* 其他说明:无
* 修改信息:无
*
************************************************************************/
不要 从 .h
文件或其他地方的函数声明处直接复制注释. 简要重述函数功能是可以的, 但注释重点要放在如何实现上。
2. 说明
全局变量一般作用于多个文件,或者整个工程,因此,其含义相对更复杂,所以在注释的时候,最好描述清楚其具体含义,就是尽量全面描述。
1. 总述
2. 说明
1. 总述
TODO
注释。TODO
注释要使用全大写的字符串 TODO
, 在随后的圆括号里写上你的名字, 邮件地址, bug ID, 或其它身份标识和与这一 TODO
相关的 issue。主要目的是让添加注释的人 (也是可以请求提供更多细节的人) 可根据规范的 TODO
格式进行查找。添加 TODO
注释并不一定意味着你要自己来修正, 因此当你加上带有姓名的 TODO
时, 一般都是写上自己的名字。注释固然很重要, 但最好的代码应当本身就是文档,有意义的类型名和变量名, 要远胜过要用注释解释的含糊不清的名字。
你写的注释是给代码阅读者看的, 也就是下一个需要理解你代码的人. 所以慷慨些吧, 下一个读者可能就是你!
推荐阅读:
16 岁高中生把 iPhone 7 改造成 Linux 服务器
5T技术资源大放送!包括但不限于:C/C++,Linux,Python,Java,PHP,人工智能,单片机,树莓派,等等。在公众号内回复「1024」,即可免费获取!!
评论