第四章 注释
来源:互联网 发布:ug8-5数控车床编程视频 编辑:程序博客网 时间:2024/06/05 06:11
- 第四章 注释
- 1 注释不能美化的代码
- 2 用代码来阐述
- 3 好注释
- 31 法律信息
- 32 提供信息的注释
- 33 对意图的解释
- 34 阐释
- 35 警示
- 36 TODO注释
- 37 放大
- 4 坏注释
- 41 喃喃自语
- 42 多余的注释
- 43 误导性注释
- 44 循规式注释
- 45 日志式注释
- 46 废话式注释
- 47 可怕的废话
- 48 能用函数或变量时就别用注释
- 49 位置标记
- 410 括号后面的注释
- 411 归属与署名
- 412 注释掉的代码
- 413 HTML注释
- 414 非本地信息
- 415 信息过多
- 416 不明显的联系
- 417 函数头
第四章 注释
4.1 注释不能美化的代码
- 不用注释,重新写;
4.2 用代码来阐述
- 简单的代码不一定能够解释其本身,给其起一个恰当的函数名称更好;
//check to see if the employee is eligible for full benefitsif ((emloyee.flags & HOURLY_FLAG)&&(emlpoyee.age>65))//优化if(employee.isEligibleForFullBenefits())
4.3 好注释
4.3.1 法律信息
- 在源文件的开头之处放置法律信息,该信息指向一个标准许可或者外部文件,不要写入全部写入文件
4.3.2 提供信息的注释
- 注释能够提供有用的信息
- 起一个好的函数名称可以不用添加注释
4.3.3 对意图的解释
- 对于一段有目的的代码,在开始处给出其解释
4.3.4 阐释
- 将晦涩难懂的参数或语句解释清楚,但存在注释错误的风险,所以在书写这类的注释时,要确保注释的正确性;
assertTrue(a.compareTo(a) == 0); // a==a 当代码改变或者复制时,不能确保及时更改注释,难以确保注释的真确性;
4.3.5 警示
- 用于警示某些代码会出现某种后果,此类注释十分必要,例如代码段将耗费大量时间,或者代码并非线程安全的
4.3.6 TODO注释
- //TODO- 类注释用于在源代码中要做的工作列表;该函数可能还没有实现,但功能应在TODO注释中表明
4.3.7 放大
- 用来放大某些看似不合理处的重要性,着重提醒重要之处
4.4 坏注释
4.4.1 喃喃自语
- 不要因为你觉得要就去写注释,代码需要才是真的需要;
- 写注释就要花时间去写出最好的注释
- 下面代码中的注释没有解释清楚默认加载是何时间进行的
public void loadProperties(){ try{ .... } catch(IOException e){ //No properties files means all defaults are loaded }}
4.4.2 多余的注释
- 当注释不能够比代码提供更多的信息时,注释纯属多余;
- 好的注释给出代码的意图、逻辑、意义;
4.4.3 误导性注释
- 注释写的不够精确,产生误导性;
4.4.4 循规式注释
- 不是每一个函数都要有注释,否则只会扰乱代码的整洁性;
4.4.5 日志式注释
- 现在利用版本控制系统可以完全避免;
4.4.6 废话式注释
- 有些插件自动生成的废话注释要删除,例如表明是构造函数的插件;
4.4.7 可怕的废话
- 避免无用的废话;
- 注意粘贴时修改;
4.4.8 能用函数或变量时就别用注释
- 取合适的函数名称代替注释;
4.4.9 位置标记
- 利用
//Actions//
此类函数分类的标记时,并且分类不多时,往往会淹没在代码中;
4.4.10 括号后面的注释
try{……}//trycatch{……}//catch
- 当觉得需要添加此类注释时,表明函数过长了,需要重构
4.4.11 归属与署名
- 没有必要,版本控制系统会添加
4.4.12 注释掉的代码
- 不要直接注释掉代码,在其他人眼中,不知道是否可以删除注释的代码
- 需要注释掉的代码直接删除,利用版本控制系统可以方便找回;
4.4.13 HTML注释
- 没有必要
4.4.14 非本地信息
- 注释一定要与代码靠近,否则函数可能修改,但注释没有修改
4.4.15 信息过多
- 没有必要在注释中添加无关细节描述;
4.4.16 不明显的联系
- 注释与代码之间的联系应该显而易见;
/** start with an array that is big enough to hold all the pixels* (plus filter bytes), and an extra 200 bytes for header info*/this.pngBytes = new byte[((this.width + 1) * this.heigh * 3) + 200];
- 该段注释中没有阐述fliter为何物
- 1、3在语句中有和中意思
- 为何选取200
- 注释本身还需注释,就是不合格的注释
4.4.17 函数头
- 短函数无需太多描述,直接取一个好的名字
阅读全文
0 0
- 第四章 注释
- 第四章:注释
- 第四章 注释
- 第四章 - 注释 - 读书心得
- OpenGl第四章 纹理详细亮度调整代码注释
- 代码整洁之道精华——第四章 注释
- POI实战-java开发excel详解(第四章 常用操作-注释)
- 实习第四天:spring注释的用法
- 第四章第四题
- 第四章第四题
- 《Linux内核完全剖析-基于0.12内核》第四章的简单多任务内核Makefile的注释
- 第四章
- 第四章
- 第四章
- 第四章
- 第四章
- 第四章
- 第四章
- mybatis mapper 传入多个参数方法
- nodejs(8.9) API通读(1)—Modules
- [CentOS7环境搭建](六)安装MySQL 5.6
- python编程练习---队列的实现
- sublime运行python程序的控制台输入
- 第四章 注释
- 康迪官网
- Eclipse 项目部署成功却访问不到 报错404
- Codeforces #453 (Div2) 题解 ABCD
- 图解SQL的inner join、left join、right join、full outer join、union、union all的区别
- Coursera深度学习课程 DeepLearning.ai 提炼笔记(1-4)
- 蓝桥杯 历届试题 兰顿蚂蚁
- hbase+python安装部署及操作
- 【SSH网上商城项目实战01】整合Struts2、Hibernate4.3和Spring4.2(转载)