《编写可读代码的艺术》的笔记-第1页

## 代码应该易于理解
* 代码的写法应当使别人理解它所需的时间最小化
* 理解代码所需的时间是否与其他目标有冲突(运行效率、更好的架构、容易测试)
## 把信息装到名字里
* 使用专业词汇 (getPage vs fetchPage, size vs height/numNodes/memoryBytes)
* 清晰和明确比抖机灵好
* 循环迭代器 (尽量用有描述性的命名，不要 i/j/k)
* 使用 tmp、it、retval 这类命名时，要有好的理由
* 带单位的值
* 附带其他重要属性 (plaintext_password, html_utf8, data_urlenc)
* 名称长度应该与其作用域正相关
* 输入长名称不应该是缩写的理由 (IDE、编辑器都支持补全)
* 尽量不使用缩略词 (SDK、PaaS 这种词除外)
* 丢掉没用的词 (convertToString vs toString)
## 无歧义的名称
* 多问自己几遍: 这个名字会被别人误解吗?
* 推荐用 first 和 last 来表示包含的范围
* 推荐用 begin 和 end 来表示包含/排除范围
## 审美
* 使用一致的风格
* 让相似的代码看上去相似
* 让相关的代码分组，形成代码块
* 风格一致性比 "正确" 的风格更重要
## 该写什么样的注释
* 注释的目的是尽量帮助读者了解的和作者一样多
* 不要为了写注释而写注释
* 不要给不好的名字加注释 ---- 应该改进命名
* 不要在注释中 "讲故事"
* 为代码中的瑕疵写注释
    - TODO: 待办事项
    - FIXME: 已知的代码缺陷
    - HACK: 对一个问题不得不采取的粗糙解决方案
    - XXX: 危险! 这里有重要问题
* 给常量加注释
* 意料之内的提问 (直接在注释中体现)
* 标明可能的陷阱
* "全局性" 注释 (架构、分层...)
* "总结性" 注释 (深入细节前就可以了解大概信息)
* 克服 "作者心里阻滞"
    - 不管心里想什么，先写下来
    - 读一下注释，看是否可以改进
    - 不断改进
## 写出言简意赅的注释
* 注释应当有很高的信息/空间率
* 避免使用不明确的代词
* 精确地描述函数的行为
* 用输入/输出例子来说明特别的情况
* 描述高层次意图，而非明显的细节
## 把控制流变得易读
* 把条件、循环及其他队控制流的改变做的越 "自然" 越好，运用一种方式使读者不用停下来重读你的代码
* 条件语句中的参数顺序 (左侧: 被询问的表达式; 右侧: 用来做比较的表达式, 更倾向于常量)
* 相对于追求最小化代码行数，一个更好的度量方法是最小化人们理解它所需的时间
* 避免 do/while 循环
* 不要纠结单一出口原则
* 避免过深的嵌套，减少循环内嵌套 
## 拆分超长的表达式
* 把超长的表达式拆分成更容易理解的小块
* 引入解释变量 (替代掉复杂的if)
* 使用德摩根定理:
    - not (a or b or c) <=> (not a) and (not b) and (not c)
    - not (a and b and c) <=> (not a) or (not b) or (not c)
* 不要滥用短路逻辑
## 变量与可读性
* 去掉没有价值的临时变量
* 减少中间结果
* 缩小变量的作用域
* 操作一个变量的地方越多，越难确定它当前的值
* 使用 const/final 修饰变量
## 重新组织代码
* 将公共代码与项目代码分离 (公共库)
* 应该把代码组织的一次只做一件事情
* 保持最小设计
* 每隔一段时间，花15分钟来阅读标准库中的所有函数/模块
* 使用 Unix 工具，而非编写代码
## 测试与可读性
* 测试应当具有可读性，以便其他人可以舒服地改变或者增加测试
* 对使用者隐去不重要的细节，以便更重要的细节会更突出
* 让错误消息具有可读性 (调用栈、描述)
* 不要追求 100% 测试覆盖率
* 不要让测试成为阻碍 (测试是为了增强质量与信心)