编程规范笔记，代码精进之路学习笔记

编程规范笔记

学习了范学雷的代码精进之路，链接：https://geek.youkuaiyun.com/educolumn/1a6591fa7f78787ce6defcb634881bbf
对第一部分的学习记录，对于安全与经济性的学习，有待更新。

好代码的标准：经济、规范、安全

1. 经济：写的又快又好、跑得又快又好、写的精简易懂
   完成时间、没有错误、运行快速、运行稳定、文本量小、清晰明了
2. 规范：通过大部分人舒服的方式，减少测试、运营、维护阶段和返工花费的时间
3. 安全：编写安全的代码

避免错误的环节

1. 程序员：注重代码风格与细节的提升（代码风格直观、逻辑简单、表述直接）
2. 编译器：重视warning，必须搞清楚warning产生的原因，尽可能的消除warning
3. 回归测试(Regression Testing)：对关键逻辑和负面清单编写测试软件
4. 代码评审(Code Review)：增加一双眼睛来阅读代码
5. 代码分析(Code Analysis)：静态代码分析（Static Code Analysis）和 代码覆盖率（Code Coverage）

优秀的程序员

掌握一门编程语言：技能基础
解决现实问题：实现价值。
发现关键问题：从被动到主动的转变。
沉静的前行者：懂得妥协，懂得选择，一步一步把事情沉静地朝前推动的人。
可以信赖的伙伴：团队意识。
时间管理者：明确自己和他人的最大价值，提高同时间的产出。

编码规范：

命名规范：

好名字：

1. 准确的意义
2. 遵守命名规范
3. 可读性优先：完整词汇>简短的名字，不使用中英文混合，避免使用拼音命名

代码整理

使用空行、空格与缩进提升视觉效果体现编码逻辑。

代码分块：

1. 单一性，一个代码块只有一个目标
2. 完整性，信息与意义完整
3. 数量适量，通常不超过25行

使用空白空间

1. 同级别代码靠左对齐
2. 同级别代码空行分割
3. 下一级代码向右缩进
4. 同行内代码空格区隔

一行一个行为

注释

注释的类型
第一种类型，是记录源代码版权和授权的，一般放在每一个源文件的开头，说明源代码的版权所有者，以及授权使用的许可方式，或者其他的公共信息。
固定的版权和授权信息，使用一般的星号注释符（/-/）
第二种类型，是用来生成用户文档的，帮助使用者了解软件的功能和细节
即生成用户文档的注释，使用Javadoc要求的格式，文档注释符（/-*/）
第三种类型，是用来解释源代码的
代码解释注释，只使用行注释符（//）行长度限制，和代码块的每行长度限制保持一致

如果一段代码不再需要，清理掉代码，而不会保留这个注释掉的代码块。

注释的原则：
准确，错误的注释比没有注释更糟糕。
必要，多余的注释浪费阅读者的时间。
清晰，混乱的注释会把代码搞得更乱。

声明：

取一个好名字
一行一个声明
局部变量需要时再声明
类属性要集中声明
声明时就初始化
尾随的花括号：
左括号不要单独成行，要紧随在语句尾部，以一个空格隔开；
右括号单独一行
靠紧的小括号
搜索优化的换行：语义相关的词语，常见的搜索模式，要尽量放在同一行

异常

运行过程中出现的错误，
出了什么错？什么地方出了错？为什么会出错？
应用程序需要处理异常（CheckedException和RuntimeException），就需要我们在方法的规范描述文档中清楚地标记异常。
对于所有的可能抛出运行时异常，都要有清晰的描述，一个也不要错过
查看所有的调用方法的规范描述，确认抛出的异常要么已经处理，要么已经规范描述。

代码段

代码头部结构
版权和许可声明；
命名空间（package）；
外部依赖（import）。

代码文件

源代码放在SRC目录下，依据组织（公司）、项目、模块的方式建立子目录
测试代码放在test的目录下
软件的文档需要跟随代码，以解释软件如何使用.

指南

交代概念
快速上手
示例可操作

检查清单

代码是按照编码指南编写的吗？
代码能够按照预期工作吗？
文件是不是在合适的位置？
支撑文档是不是充分？
代码是不是易于阅读、易于理解？
代码是不是易于测试和调试？
有没有充分的测试，覆盖关键的逻辑和负面清单？
名字是否遵守命名规范？
名字是不是拼写正确、简单易懂？
名字是不是有准确的意义？
代码的分块是否恰当？
代码的缩进是否清晰、整洁？
有没有代码超出了每行字数的限制？
代码的换行有没有引起混淆？
每一行代码是不是只有一个行为？
变量的声明是不是容易检索和识别？
变量的初始化有没有遗漏？
括号的使用是不是一致、清晰？
源代码的组织结构是不是一致？
版权信息的日期有没有变更成最近修改日期？
限定词的使用是不是遵循既定的顺序？
有没有注释掉的代码？
有没有执行不到的代码？
有没有可以复用的冗余代码？
复杂的表达式能不能拆解成简单的代码块？
代码有没有充分的注释？
注释是不是准确、必要、清晰？
不同类型的注释内容，注释的风格是不是统一？
有没有使用废弃的接口？
能不能替换掉废弃的接口？
不再推荐使用的接口，是否可以尽早废弃？
继承的方法，有没有使用Override注解？
有没有使用异常机制处理正常的业务逻辑？
异常类的使用是不是准确？
异常的描述是不是清晰？
是不是需要转换异常的场景？
转换异常场景，是不是需要保留原异常信息？
有没有不应该被吞噬的异常？
外部接口和内部实现有没有区分隔离？
接口规范描述是不是准确、清晰？
接口规范有没有描述返回值？
接口规范有没有描述运行时异常？
接口规范有没有描述检查型异常？
接口规范有没有描述指定参数范围？
接口规范有没有描述边界条件？
接口规范有没有描述极端状况？
接口规范的起草或者变更有没有通过审阅？
接口规范需不需要标明起始版本号？
产品设计是不是方便用户使用？
用户指南能不能快速上手？
用户指南的示例是不是可操作？
用户指南和软件代码是不是保持一致？