- 外部文档
- 大项目的文档往往放在源代码之外
- 单元开发文件:是一种非正式的文件,给开发人员在开发的时候查看
- 详细设计文档:描述类/方法级别的设计细节,是一种正式文档
- 良好的编程风格可以作为文档
- 到底要不要注释呢?
- 良好的注释是很有价值的,但是不好的注释不但浪费时间,而且影响代码质量
- 良好注释的关键
- 注释的种类
- 重复代码的意思:完全没用
- 解释代码:说明代码太复杂了,需要改进
- 作为记号:最好使用标准化的记号,比如TODO记号
- 代码的摘要:当别人需要修改代码时能起到很好的作用
- 描述代码的意图:比代码摘要还要好用
- 解释代码无法说明的问题,比如版本号、作者等:可以用javadoc中的标准记号来表示
- 高效的注释方法
- 写注释很花费时间
- 保持注释风格很浪费时间
- 代码的原理很难描述
- 几点指导
- 注释的风格不要太华丽,很难修改
- 短注释用//,长注释用/**/
- 将注释像代码一样整合在代码中
- 写注释很花费时间
- 应该写多少注释比较合适
- 1条注释对应10行代码比较合适
- 但是千万不能强制要求写注释,不然注释都是没有用的
- 注释的种类
- 注释技术
- 对单行代码进行注释
- 理由
- 这行代码太复杂了,需要额外的解释
- 这行代码曾经出现过错误,需要记下这种错误
- 几点意见
- 注释的时候不要想写什么就写什么
- 注释放在一行代码的末尾
- 问题
- 这样的注释需要对齐,修改起来很麻烦
- 这样的注释很难维护
- 这样的注释往往解释不清,因为书写空间有限
- 尽量不要把注释放在一行代码的末尾
- 最根本的问题是单行代码其实很难写出有意义的注释
- 这样的注释不要写给多行代码,容易造成误解
- 什么时候应该使用这种注释
- 注释变量的时候。不要在注释中写上缺陷的修复过程,注释要解释现在为什么可以用,而不是为什么以前不能用
- 标记一个代码块的结束
- 问题
- 理由
- 注释一段代码
- 注释的时候主要写出代码的意图
- 注释的时候关注为什么这样写,而不是这段代码的运行原理
- 注释最好是代码预告,预告下一段代码准备做什么
- 让每行注释有有它的价值
- 记录代码中让人意想不到的事情,比如使用了特殊方法来提高性能,这时候要写明这种方式能提升多少性能
- 注释的时候不要缩写
- 注释分为主要注释和次要注释
- // Major blablablabla
- 大量代码
- // ... minor blablabla 次要注释
- 大量代码
- // ... minor blablabla 次要注释
- 注释库中的一些不明显的特性/BUG,并解释如何绕过这个特性/bug
- 不要给误导性的代码加注释,要重写代码
- 给变量增加注释
- 注释变量的单位,米/毫米/秒/毫秒?
- 可以在变量名称中包含变量的单位
- 注释变量的取值范围
- 注释编码的意思。比如1代表正常,0代表未审核,-1代表删除等
- 如果变量是按位的话,注释每个位的含义。在网络编程中可能用到多一些
- 注意,当变量的含义发生变化时,注释也要跟着变化
- 注释全局变量的含义
- 注释变量的单位,米/毫米/秒/毫秒?
- 给控制结构增加注释
- 控制结构的上一行往往都是用来放置注释的,解释代码的目的
- 将代码放在if/case/loop/代码块的上一行
- 将注释放在代码块结束的地方,比如
- for(xxxIndex...){
- ...
- } // for xxxIndex - 处理每条用户记录
- 这种注释往往意味着循环太复杂,需要改进
- 给函数增加注释
- 将注释放在离代码最近的地方
- 在每个函数的顶部用一句或两句话描述函数
- 给参数增加注释
- 每行一个参数,每个参数一句注释
- 也可以通过javadoc中的@param关键字来增加注释
- 给参数写注释的时候要强调输出参数和输入参数的区别
- 如果这个函数给参数作了假设,应当在注释中写出
- 如果这个函数使用了全局变量,应当在注释中写出
- 注释这个函数的局限
- 注释这个函数对全局变量的影响
- 注释这个算法的来源(某某书第几页)
- 在注释中写上标记,比如@keyword @param @author等
- 给一个类增加注释
- 描述类的设计思路
- 在注释中写上类中包含的接口
- 不要在注释中写上接口的实现细节
- 给一个文件增加注释
- 描述这个文件的目的
- 如果这个类中包含多个类,应该在注释中注明为什么要多个类
- 在注释中写上作者的详细信息,有助于团队协助
- 在注释中写上版本信息
- 法律信息
- 文件名要和文件中的内容一致
- 程序就像一本书
- 序言
- 目录
- 章节
- 参考
- 这种结构详细描述了程序的高级接口和低级结构
- 对单行代码进行注释
- IEEE标准
- 软件开发标准
- IEEE Std 830-1998
- IEEE Std 1233-1998
- IEEE Std 1016-1998
- IEEE Std 828-1998
- IEEE Std 1063-2001
- IEEE Std 1219-1998
- 软件质量标准
- IEEE Std 730-2002
- IEEE Std 1028-1997
- IEEE Std 1008-1987
- IEEE Std 829-1998
- IEEE Std 1061-1998
- 管理标准
- IEEE Std 1058-1998
- IEEE Std 1074-1998
- IEEE Std 1045-1992
- IEEE Std 1062-1998
- IEEE Std 1540-2001
- IEEE Std 1490-1998
- 软件开发标准