看一份源码什么很重要?除了各种代码规范之外,还有一个比较重要的就是注释。
注释虽然写起来很痛苦, 但对保证代码可读性至关重要,下面我们就**以C/C++代码规范注释****为例**,将描述如何注释以及有哪些讲究。
**注释风格**
**1\. 总述**
一般使用 `//` 或 `/* */`,只要统一就好。
**2\. 说明**
`//` 或 `/* */` 都可以,但团队要在如何注释及注释风格上确保统一。
**文件注释**
**1\. 总述**
在每一个文件开头加入版权、作者、时间等描述。
文件注释描述了该文件的内容,如果一个文件只声明,或实现,或测试了一个对象,并且这个对象已经在它的声明处进行了详细的注释,那么就没必要再加上文件注释,除此之外的其他文件都需要文件注释。
**2\. 说明**
法律公告和作者信息:
每个文件都应该包含许可证引用。也要为项目选择合适的许可证版本(比如,[**Apache 2.0, BSD, LGPL, GPL**](http://mp.weixin.qq.com/s?__biz=MzI4MDI4MDE5Ng==&mid=2247490542&idx=1&sn=489b574b83cb8a3a5e80b26e8037f8f2&chksm=ebbbb605dccc3f138bfa917e47ae3d347254ff88c2d42ccdb6b7493fcdb38f579b88c657939d&scene=21#wechat_redirect))。
**3\. 文件内容**
如果一个 `.h` 文件声明了多个概念, 则文件注释应当对文件的内容做一个大致的说明, 同时说明各概念之间的联系。一个一到两行的文件注释就足够了, 对于每个概念的详细文档应当放在各个概念中, 而不是文件注释中。
不要在 `.h` 和 `.cc` 之间复制注释, 这样的注释偏离了注释的实际意义。
最后再举个最简单的实际例子:
~~~
/************************************************************************
~~~
**函数注释**
**1\. 总述**
函数声明处的注释描述函数功能; 定义处的注释描述函数实现。
**2\. 说明**
**函数声明:**
基本上每个函数声明处前都应当加上注释, 描述函数的功能和用途。只有在函数的功能简单而明显时才能省略这些注释(例如, 简单的取值和设值函数)。
比如:
~~~
/************************************************************************
~~~
**函数定义:**
如果函数的实现过程中用到了很巧妙的方式, 那么在函数定义处应当加上解释性的注释。比如, 你所使用的编程技巧, 实现的大致步骤, 或解释如此实现的理由。举个例子, 你可以说明为什么函数的前半部分要加锁而后半部分不需要。
*不要* 从 `.h` 文件或其他地方的函数声明处直接复制注释. 简要重述函数功能是可以的, 但注释重点要放在如何实现上。
**变量注释**
**1\. 总述**
通常变量名本身足以很好说明变量用途, 某些情况下, 也需要额外的注释说明。
**2\. 说明**
根据不同场景、不同修饰符,变量可以分为很多种类,总的来说变量分为全局变量、局部变量。
一般来说局部变量仅限于局部范围,其含义相对简单容易理解,只需要简单注释即可。
全局变量一般作用于多个文件,或者整个工程,因此,其含义相对更复杂,所以在注释的时候,最好描述清楚其具体含义,就是尽量全面描述。
(提示:全局变量尽量少用)
**拼写注释**
**1\. 总述**
可能一个变量、一个函数包含的意思非常复杂,需要多个单词拼写而成,此时对拼写内容就需要详细注释。
**2\. 说明**
注释的通常写法是包含正确大小写和结尾句号的完整叙述性语句。大多数情况下, 完整的句子比句子片段可读性更高。短一点的注释, 比如代码行尾注释, 可以随意点, 但依然要注意风格的一致性。
同时,注释中的拼写、逗号也很重要。虽然被别人指出该用分号时却用了逗号多少有些尴尬, 但清晰易读的代码还是很重要的。正确的标点, 拼写和语法对此会有很大帮助
**TODO 注释**
**1\. 总述**
对那些临时的, 短期的解决方案, 或已经够好但仍不完美的代码使用 `TODO` 注释。
`TODO` 注释要使用全大写的字符串 `TODO`, 在随后的圆括号里写上你的名字, 邮件地址, bug ID, 或其它身份标识和与这一 `TODO` 相关的 issue。主要目的是让添加注释的人 (也是可以请求提供更多细节的人) 可根据规范的 `TODO` 格式进行查找。添加 `TODO` 注释并不一定意味着你要自己来修正, 因此当你加上带有姓名的 `TODO` 时, 一般都是写上自己的名字。
**结 语**
注释固然很重要, 但**最好的代码应当本身就是文档**,有意义的类型名和变量名, 要远胜过要用注释解释的含糊不清的名字。
你写的注释是给代码阅读者看的, 也就是下一个需要理解你代码的人. 所以慷慨些吧, 下一个读者可能就是你!
- 重要文档
- 工作须知
- 项目下的公共方法
- 程序员给代码写注释时有哪些讲究!
- RestFul 讲解
- 其他知识
- docker容器
- MongoDB的使用
- Node.js的使用
- Session共享
- Wordpress的使用
- Websocket的简介
- Ajax
- 项目技术
- Https配置证书
- Nginx的反向代理
- MySQL读写分离配置(laravel篇)
- Nginx的负载均衡
- App接口返回格式
- laravel中JWT的应用
- laravel验证码的使用
- laravel公共方法文件
- laravel框架的RBAC
- Git相关
- Git篇1
- Git篇2
- Mysql相关
- Mysql的主从复制
- MySQL的备份
- MySQL的使用
- 请求第三方接口
- Redis相关
- redis的使用
- Redis的基本用法以及场景分析
- 开发小技巧
- Linux
- 禁用root及密码登录
- Lnmp环境的安装
- 安装composer
- 安装Redis
- 文件共享服务 samba
- 其他安装
- Lnmp常用命令
- 性能检测命令
- Nginx的配置详解
- PHP相关
- PHP基础知识
- php常见的系统函数
- PHP的设计模式
- Cookie 和 Session 的封装
- Mysql知识
- Mysql索引
- MySQL的数据类型
- PHP重要知识
- PHP框架篇
- Laravel框架
- laravel---Excel
- laravel文件上传
- Laravel-Mysql常用操作
- Laravel队列(queue)
- laravel-发送Email
- laravel--JWT
- TP框架篇
- tp5主从数据库设置读写分离
- 前端
- JS
- js代码实现点击按钮出现60秒倒计时
- 开发软件相关
- 代码编辑器
- vs code配置ftp连接远程服务器实现代码文自动上传
- 编程相关软件下载