代码简洁之道的笔记--1

本文写于本人参加工作之初，学习写代码规范，以便对自己的代码进行审视反思；
1、整洁代码只做好一件事；
2、整洁代码从不隐藏设计者的意图；

命名

• 名副其实：
  变量、函数或者类的名称已经说明了其代表的含义，如果还需要注释帮助说明，就不算名副其实；
  要从其本身的含义和作用出发，明确地、有意义地一语道破该函数干了啥；
• 避免误导：
  变量类型和名字要对上，不要造成命名和意义不同；
• 做有意义的区分：
  products
productlist
  或者是
  productdata
productinfo
  这种命名是含糊不清的，要做到有意义的区分
• 命名规则尽量：
  使用读出来的名称；
  使用可搜索的名称；
  每个概念对应一个词；
  添加有意义的语境；

注释

注释会撒谎。由于程序员不能及时维护注释，其存在的时间越久，离其描述的代码越远；最后可能全然错误。真实只在一处地方存在：代码。

好注释

1. 法律相关注释；
2. 对写这段代码的意图的解释
   //这个线程数是我们尝试过得到最好效果的数值
for(int i = 0; i <5000; i++) { }
3. 解释：
   对于某些不能更改的代码，对其入参、返回值等进行解释；
4. 警告：
   对于某些需要注意的代码，警告某些后果也是被支持的；
   对于某些不合理的代码，也可以用注释来告诉阅读者其用途和重要性；
5. TODO：
   来不及做的，使用TODO进行注释--需要定期清理；
6. 做公共文档的API时：
   要写出通俗易懂的注释，避免使用者啃源码需要的时间；

坏注释

1. 只是用来写给自己看的；
2. 多余的注释：
   对于简单的函数和代码，不必写注释，不然读注释时间比读代码时间还长；
3. 括号后的注释：
   一般不在括号后添加注释，代码和注释不混在一行；（各种莫名奇妙的数字不如给他们定义常量名，方便读也方便用）
4. 归属和签名：
   这种事情由源码控制系统来做；不需要手动添加签名；越久远的代码越不准确；
5. 注释掉的代码：
   一大串注释掉的代码会让人看着心烦，其他人可能会以为这是很重要的代码而不敢删除。
6. 更多情况：
   需要注释的注释；注释和代码无关；非公共代码的doc类注释。