表面层次的改进包括:选择好的名字、写好的注释、以及把代码整洁地写成更好的额格式。这些很重要,因为会影响到你代码库中的每行代码。
第二章 把信息装到名字里
选择专业的词
避免泛泛的名字(要知道什么时候使用它)
用具体的名字代替抽象的名字
使用前缀或后缀来给名字附带更多信息
决定名字的长度
利用名字的格式来表达含义
1.清晰和精确比装可爱好
找到更有表现力的词
send | deliver dispatch announce distribute route |
find | search extract locate recover |
start | launch create begin open |
make | create set up build generate compose add new |
2.避免泛泛的名字
retval这个名字没有包含很多信息,用一个描述该变量的值得名字来代替它。
tmp这个名字只应用于短期存在且临时性为其主要存在因素的变量。
循环迭代器像i,j,iter,it等使用具体信息与其组合使用可能会更有帮助。
建议:如果要使用像tmp,it或者retval这样空泛的名字,那么你要有个好的理由。
很多时候,仅仅是因为懒惰而滥用它们。
3.用具体的名字代替抽象的名字
在给变量、函数或者其他元素命名时,要把它描述得更具体而不是更抽象
1)为名字附带更多信息:一个变量名就像一个小小的注释。
例如一个包含十六进制字符串的变量,string id; 可以改名为hex_id。
2)带单位的值
delay | ----->>>> | delay_secs |
size | size_mb | |
limit | max_kbps | |
angle | degree_cw | |
3)附带其他重要属性
例如,很多安全漏洞来源于没有意识到程序接收到的某些数据还没有处于安全状态。可能用到
untrustedUrl ----->> trustedUrl
unsafeMessageBody ----->> safeMessageBody
情形 | 变量名 | 更好的 |
一个“纯文本”格式密码,需要加密之后才能进一步使用 | password | plaintext_password |
一条用户提供的注释,需要转义之后才能用于显示 | comment | unescaped_comment |
已转化为UTF-8格式的html字节 | html | html_utf8 |
以“url方式编码”的输入数据 | data | data_urlenc |
应该在如果有人物价变量就很容易产生缺陷,尤其是像安全缺陷这样的地方。基本上,如果这是一个需要理解的关键信息,那么就把它放在名字里。
4.名字的长度
小的作用域里可以使用短的名字;如果一个标识符有较大的作用域,那么它的名字就要包含足够的信息以便含义更清楚。
注意利用编辑器的“单词补全”功能,Vi(Ctrl+p) Eclipse(Alt+/)
注意首字母缩略词和缩写的使用,经验原则是:团队的新成员能否理解这个名字的含义?如果能,则没有问题。
丢掉没用的词 ConvertToString -> ToString, DoXXXX -> XXXX
5.利用名字格式传递含义
类名:CameCase 变量名:lower_separated
常量 kConstantName #define宏 CONSTANT_NAME (MACRO_NAME)
类成员变量以下划线结尾如 offset_
Java 中构造函数首字母大写而普通函数首字母小写;
HTML/CSS中,用下划线分开ID中的单词,用连字符分开class中的单词。
<div id="middle_column" class="main-content">
总结
使用专业的词--例如不用get,而用Fetch或者Download,这由上下文决定;
避免空泛的名字--像tmp,retval,除非有使用它们的特殊理由;
使用具体的名字来更细致地描述事物--ServerCanStart()比CanListenOnPort()更不清楚。
给变量名带上重要的细节--例如,在值为毫秒的变量后面加上_ms,或者在还需要转义的,未处理的变量前面加上raw_。
为作用域大的名字采用更长的名字--不要让人费解的一个或者两个字母的名字来命名在几屏之间都可见的变量。对于只存在与几行之间的变量用短一点的名字更好。
有目的地使用大小写,下划线等--例如在类成员和局部变量后面加上"_"来区分它们。