给代码写注释时有哪些讲究？
Python 知识大全
共 3809字，需浏览 8分钟
·
2021-01-15 19:30
（点击上方快速关注并设置为星标，一起学Python）
整理/来源丨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. 说明
TODO 注释
1. 总述
TODO 注释。
TODO 注释要使用全大写的字符串 TODO, 在随后的圆括号里写上你的名字, 邮件地址, bug ID, 或其它身份标识和与这一 TODO 相关的 issue。主要目的是让添加注释的人 (也是可以请求提供更多细节的人) 可根据规范的 TODO 格式进行查找。添加 TODO 注释并不一定意味着你要自己来修正, 因此当你加上带有姓名的 TODO 时, 一般都是写上自己的名字。
结 语
注释固然很重要, 但最好的代码应当本身就是文档，有意义的类型名和变量名, 要远胜过要用注释解释的含糊不清的名字。
你写的注释是给代码阅读者看的, 也就是下一个需要理解你代码的人. 所以慷慨些吧, 下一个读者可能就是你！
最后给大家推荐视频号，每天更新爬虫实战视频，干货货多多。
点「在看」的人都变好看了哦
评论