OO编程基本功(3) 注释
1. 避免依赖注释来逃避重构
注释在code中可以使得代码更容易理解,可是相当多的情况下,它会使得程序员过于“依赖”注释而容许代码的自我说明程度降低。
需要注释?是否代码名称不够清晰,或者代码的抽象层次混乱,还是代码的动机不够明确导致需要注释来做额外说明?合格的代码本身一般是不需要额外注释的。
例如:
//newPasswordMUST at least 6 digits
User.Password= newPassword ;
可以重构为:
privateconst string PASSWORD_MIN_LENGTH = 6;
publicvoid ChangePassword(string newPassword){
Assert.IsTrue(newPassword.Length>= PASSWORD_MIN_LENGTH );
User.Password= newPassword;
}
再如:
//Employeeis eligible to retire
if(Employee.Age> 65 && Employee.Payed){
...
}
重构为:
if(Employee.EligibleToRetire){
}
privatebool EligibletoRetire{
get{
returnthis.Age > 65 && this.Payed;
}
}
什么时候使用注释
既然重构是使得code更加清晰的主要手段,那么什么时候使用注释?
1. 公司版权的说明
// Copyright (C) 2003,2004,2005 by XXX. All rightsreserved.
2. sample
var date = new Date("dd-MM-yyyy"); // sample: 10-11-2014
3.一些必要的注解说明
例如
if(...){
return 0 ;
}
return 1 ; // 1: eligible 2 :non-eligible
再如在单元测试中,测试性能
for(var i = 0;i < 1000/*并发一千个线程来模拟高并发情况*/; i++){
}
再如,还是多线程情况(提醒共享资源环境下,别忘了对多线程访问的考虑):
//do not forget take care of multi-thread scenarios
var resource = new ShareResource();
4.TODO
例如:
User.Login();
//TODO : finish order logic
不必要的注释
1. 以注释来逃避代码不完善的理由
try {
LoadFiles();
}
Catch(IOException exp){
//Do nothing
}
如果swallow这个异常,那么为什么要捕捉这个异常?更没有必要用一个注释来作为什么都不做的理由。
2. 啰嗦的注释
//1.Student Age > 6
//2.Region is valid
public void IsEligible(Student student){
...
}
注释完全没有必要把代码的实现逻辑写在函数头。可以用注释来引导自己去写代码的实现,但是实现之后建议及时清理掉以免代码逻辑修改后造成与代码不同步形成误导。毕竟,代码是唯一不会说谎的。(软件UI,文档,注释都会“说谎”)
3. 没必要为每个property , member都写一个说明
/**
* The Manager implementation with which this Containeris
* associated.
*/
protected Manager manager = null;
/**
* The cluster with which this Container is associated.
*/
protected Cluster cluster = null;
/**
* The human-readable name of this Container.
*/
protected String name = null;
显然,如果为每个字段,属性,方法都写注释,看上去很统一,却严重影响了代码的可读性。代码本身应该具备自我解释的能力,如果发现需要注释来弥补,则应考虑重构。
4. 不必要的日志注释
例如:
* Changes (from 11-Oct-2001)
* --------------------------* 11-Oct-2001 :Re-organised the class and moved it to new package
* com.jrefinery.date (DG);
* 05-Nov-2001 : Added a getDescription() method, andeliminated NotableDate
* class (DG);
* 12-Nov-2001 : IBD requires setDescription() method,now that NotableDate
* class is gone (DG); Changed getPreviousDayOfWeek(),
* getFollowingDayOfWeek() and getNearestDayOfWeek() tocorrect
* bugs (DG);
* 05-Dec-2001 : Fixed bug in SpreadsheetDate class(DG);
* 29-May-2002 : Moved the month constants into aseparate interface
* (MonthConstants) (DG);
* 27-Aug-2002 : Fixed bug in addMonths() method,thanks to N???levka Petr (DG);
* 03-Oct-2002 : Fixed errors reported by Checkstyle(DG);
* 13-Mar-2003 : Implemented Serializable (DG);
* 29-May-2003 : Fixed bug in addMonths method (DG);
* 04-Sep-2003 : Implemented Comparable. Updated theisInRange javadocs (DG);
* 05-Jan-2005 : Fixed bug in addYears() method(1096282) (DG);
这种注释看上去好像很整齐,当前好多公司都在follow,其实完全没有必要,因为source control已经为我们做了同样的事情,这种注释只会降低代码的可读性,长时间以后提供的信息也完全没有人会去看。
5. 噪音注释需要屏蔽
/**
* Default constructor.
*/
protected Student() {
}
谁不知道这是默认构造函数呢?
再如:
/**
* Returns the day of the month.
*
* @return the day of the month.
*/
public int getDayOfMonth() {
return dayOfMonth;
}
这样的注释如果是一种规范,那么完全没有必要和意义。
6. 避免署名注释
//added by Richard
和日志注释一样没有必要,source control 工具已经为我们做了同样的事情。
7. 避免“暂时注释掉”的代码
InputStreamResponse response = newInputStreamResponse();
response.setBody(formatter.getResultStream(),formatter.getByteCount());
// InputStream resultsStream =formatter.getResultStream();
// StreamReader reader = newStreamReader(resultsStream);
//response.setContent(reader.read(formatter.getByteCount()));
往往由于“不舍得”删而暂时放在那里,以后可能会用到?果断拿掉吧,sourcecontrol 会帮你存好的,为了其它coder阅读起来舒服,避免造成误导。
分享到:
相关推荐
C_OO思想编程
北航第三次oo作业,在原来傻瓜电梯的基础上增加捎带功能
面向对象,编程,OO设计的五大原则 OO的五大原则是指SRP、OCP、LSP、DIP、ISP。
详细介绍建模、面向对象和UML的课件。 第一部分通过例子阐明了建模的...第三部分从OO思想的角度说明面向对象的基本概念,以及为什么会有这些概念。 第四部分阐明了为什么需要UML、UML带来的什么、UML的发展历史和组成。
移动互联网应用
这个是关于面向对象的基本特征! 很详细啊
希望这个介绍PHP5面向对象编程(OOP)的资料能让初学者受益,能让更多的PHPer开始转向OO的编程过程。 相对PHP4,PHP5在面向对象方面改变了很多。我们将只介绍PHP5环境下的面向对象。而我们必须改变自己来跟随PHP5的...
函数式编程目前已跟OO一样,是一种重要的编程范式,可以在一些场合下更容易的解决相关问题。
实战OO_用例建模 实战OO_用例建模 实战OO_用例建模
用 C 语言实现面向对象编程,我曾经在嵌入式控制系统工作过,苦于嵌入式系统编程一直是 C 语言,而没法用 C++或其他...至此,C 的 OO 编程中的封装、继承、多态都全实现了。现在 本人将其总结如下,希望对大家有帮助。
OO中对于23种设计模式的整理OO中对于23种设计模式的整理
oo学习
3、Windows XP/WIN7/win10系统(64位系统对应64位dll文件,32位系统对应32位dll文件),将oo2core_6_win64.dll复制到C:\Windows\System32目录下。 4、如果您的系统是64位的请将32位的dll文件复制到C:\Windows\SysWOW64...
面向对象编程(Object Oriented Programming,OOP,面向对象程序设计)是一种计算机编程架构。 基本概念: 1.对象(Object)是一个现实实体的抽象。一个对象可被认为是一个把数据(属性)和程序(方法)封装在...
讲 师:蒋林峰 课程简介:面向对象是一种先进的编程技术,有利于大型项目的开发和管理。...课程从实例出发,详细演示设计的过程和实际的操作,适合于OO编程的初学者,也适合计划从VB6编程转向VB.NET编程的用户。
ABAP OOALV报表开发,定义变量,选择屏幕定义,创建类,调用函数,是学习OOALV很不错的学习资料
OOALV常用功能完整简例,OO ALV常用功能完整简例 - OO ALV 常用功能完整简例(热键单击,双击,帮助,编辑,自定义工具条等)
【ASP.NET编程知识】ASP.NET Web API如何将注释自动生成帮助文档.docx
除了学习基本的Java语法以及如何用Java表达OO概念外,还讨论了实用主题,例如小程序,图形,数据存储,多线程编程和异常处理。 1.2先决条件 学生必须具有成功完成MCT612应用程序编程所达到的标准的程序语言(例如C...
北航OO课的作业代码,从电梯到出租车,你想要的都在里面。注释充足,供有需要的同学参考(切勿抄袭哦~)