The Art of Readable Code
图书馆无意间看到的一本书,经常被大佬室友吐槽我的代码写的很难读,变量命名啥的一塌糊涂。所以想通过阅读这本书,找点经验。
表面层次的改进
一、把信息装进名字
写完突然想到一篇文章,去翻了翻 知乎.
介绍如何命名的文章
一个好的命名网站命名网站.
- 选择专业的词 要能很好的表达意思 类似get,tmp,就表意不明,用FetchPage() 就更好
- 选择更加具有表现力的词
- i,j,k是常用的循环迭代器,别用作他用。但有时候根据情况,可以在前面加上变量前缀,让迭代器表示的意义更加清晰。例如 club_i、user_i…
- 切记在使用空泛名字时要谨慎。没有好的理由不要偷懒。
- 用具体的名字代替抽象的名字。
- 为名字附带更多的信息。 变量名像个小小的注释。要利用好。
- 有单位的话最好带上单位,避免引起分歧。例如 delay_secs, size_mb…
- 附加其他的属性 例如微软的匈牙利表示法 ——将每个变量的“类型”信息写进名字里。
- 名字的长度不宜太长,也不宜太短。
- 小的作用域可以使用短的名字
- 长的作用域,例如全局变量等,名字命名就要可以适当长一点,包含更多的信息。
- 有目的的使用下划线和大小写等用来区分
。。。去吃了个饭,没有保存,后面写的全部被删了,艹。。。
二、不会误解的名字
- 不要使用有歧义的词做名字,避免给别人造成误解。
- 命名极限最清楚的方式是要在限制的东西前面加上max_ , min_ 的前缀。
- 推荐使用first和last来表示包含的范围。
- 推荐使用begin end 来表示包含/排除的范围。
- 给布尔变量命名时应注意以下几点:
- 确保返回的true 和 false 的意义很明确。
- 通常来说,加上is , has , can, should, 这样的词来将布尔变量的值更加明确。
例如:
bool is_primer(int x);
- 避免使用反义名字
bool disable_ssl = false; // 不好
bool use_ssl = ture; //好
- 与使用的期望相匹配。有些名字之所以误解是因为有先入为主的印象,尊重他。eg . 用户会期待 get(),size()是轻量的方法。
三、审美
- 使用一致的布局,让读者很快习惯这种风格。
- 让相似的代码看上去相似。
- 把相关的代码分组,形成代码块。
- 重新安排换行来保持一致和紧凑性。
- 注意列的对齐,很重要,不重复。
- 用空行把大块的代码分成逻辑上的段落。
- 看下面这个:
class Logger {
...
};
class Logger
{
...
};
像是其他争端一样,这个争端在程序员中也很常见,关乎信仰问题。PS:我觉得第一个更好。
选择这两种的任意一种都没有问题,但是如果你在代码中采用了这两种风格,那就会影响代码的可读性。
因此,个人风格要保持一致性。一致的风格比正确的风格更重要。
四、该写什么样的注释
- 不要给那些从代码本身能快速推断的事实写注释。
- 不要为了注释而注释,否则会造成代码臃肿。
- 不要给不好的名字写注释——应该把名字改好 好代码 > 坏代码 + 好注释
- 注释应当记录下你重要的思想
- 注释应当写成“导演评论”
//哈希运算的代价比左边大得多
//作为整体可能会丢掉几个词。这没有问题,要100%解决这个问题太难了。
//注释应当写下你对这段代码有价值的见解
- 为代码中的瑕疵写注释
//TODO:这里应该有更好的算法
//TODO:我想到了一个绝妙的证明方法,不过这里空太小,我写不下了。回来有时间写。
//XXX:这里有个大BUG,不要碰,否则后果自负!