代码整洁之道（一）

一、有意义的命名

1.要名副其实，不要模糊，int elapsedTimeInDay好于int d。

2.避免误导，避免用小写字母l和大写字母O做变量，误导1/0；不要用accountList指一组账号，除非它是一个List类型，用accounts较好；避免使用多个区分较小的词做长名字，易看错。

3.做有意义的区分，src／dst好于a1/a2；不要同时用ProductInfo和ProductData，info和data类似a／an／the难区分；variable／class／table等不要出现于于变量名／类名／表名中，没意义。

4.使用读得出来的名称，用英文不要用自造词，如用generationTimestamp不用genmdhms表示生成时间戳。

5.使用可搜索的名称，单字母名称和数字常量很难在大篇文章中找出来，MAX_CLASSES_PER_STUDENT比数字7好找；名称长短应该和作用域大小相对应。

6.避免使用编码，匈牙利命名不用加类型，尽量消除成员前缀，String description优于m_des。

7.避免思维映射，ijk多数表示循环计数器，其他地方尽量少用。

8.类名和对象名，用名字或名词短语，如Customer／WikiPage／Account／AddressParser，避免Manager／Processor／Data／Info这些。

9.方法名，用动词或动词短语，如postPayment／deletePage／save等，或加get／set／is前缀。

10.每个概念对应一个词，fetch／get／retrieve均使用get，controller/manager/driver均使用controller。

11.添加有意义的语境，addrFirstName/addrLastName/addrState优于firstName／lastName／state，但最好用类表示。

二、注释

1.注释的恰当用法是弥补我们用代码表达意图时遭遇的失败，与其花时间写注释，不如去清洁代码，尽量减小注释量。

2.用代码阐述，通过创建一个与注释所言同一事物的函数即可

if(emplyee.isEligibleForFullBenefits()),好于下面两行

//check to see if the employee is eligible for full benifits

if((employee.flags&&HOURLY_FLAGS)&&(emplyee.age>65))

3.哪些是好注释

（1）法律信息，有时公司要求编写与法律有关的注释，作为标准注释，放在每个源文件的开头，IDE可以自动卷起这些注释。

（2）提高信息的注释，这类一般可以通过变量或函数重命名避免。

（3）有意图的解释，如This is the best attempt to get a race condition by creating a large number of threads.

（4）阐释，把一些晦涩难明的参数或返回值翻译成可读的形式，正确性有风险。如assertTrue（a.compareTo(b)==-1）//a<b

（5）警示，如Don't run unless you have some time to kill。也可以用@Ignore属性关闭测试用例，如@Ignore（“take too long to run！”）

（6）TODO注释，解释应该做但由于某些原因没有完成的工作，应该定期查看删除。

（7）放大，强调一些不合理之物的重要性。

（8）公共API中的javadoc，文档，但也可能会误导或提供错误信息。

4.哪些是坏注释

（1）喃喃自语，废话注释，误导性注释

（2）函数头以及简单函数头部位置的注释，

（4）日志式注释&&归属和署名，如修改纪录，修改作者修改时间等，因为有代码控制系统，这类代码应全部删除。

（5）位置标记，少用标记栏，只在特别有价值的地方用。如//Action///

（6）右括号后面的注释，对于含有深度嵌套结构的长函数有用，但会给小函数带来混乱。

（7）没用的代码，直接删掉而不是注释掉。

（8）HTML注释