代码精进之代码规范(二)

代码整理的关键逻辑

• 一个好的程序员，要识别并且区分代码块，让它们易于阅读和辨认。

程序代码分块时，我们需要注意以下三个点:

• 保持代码块的单一性，一个代码块只能有一个目标。代码块内所有的内容都是为了一个目标服务的，不能把无关的内容放在同一个代码块里。同一个代码块里语句的相互联系比与相邻代码块里的语句关系更为紧密；
• 注意代码块的完整性。代码块是一个完整的信息块。一个代码块要表达一个相对完整的意思，不能一个意思没说完就分块了，就像话说了半句一样；
• 代码块数量要适当。代码块过多，会让人觉得路径太长，逻辑复杂，不容易阅读理解。一个基础的代码块最好不要超过 25 行（通常显示屏小半个页面），否则就会有增加阅读理解的困难。

给代码分块的办法之一，就是有效地使用空白空间。

• 同级别代码块靠左对齐：阅读的习惯顺序是从左到右，代码也如此。因此不同行，但同级别的代码要靠左对齐。
• 同级别代码块空行分割：阅读代码总是从上往下读，不同行的同级别的代码块之间，要使用空行分割。
• 下一级代码块向右缩进：区分不同行的不同级别的代码，可以使用缩进。缩进的目的是为了让我们更直观地看到缩进线，从而意识到代码之间的关系。
• 同行内代码块空格区隔：位于同一行内的代码块，同样需要注意。我们可以使用空格区分开不同的逻辑单元。
  • 比如逗号分隔符后要使用空格，以区分开下一个信息。
  • 双目运算符或者多目运算符，运算符前后都要使用空格。

一个重要的原则是，每一行代码仅仅表示一个行为。这样每一行的代码才是一个常规大小的、可以识别的基础信息块。

代码分块的基本思想，同样适用于换行。基本的换行规范需要考虑以下三点

• 每行代码字符数的限制。一般情况下，每行代码不要超出 80 个字符（ 80 个字符是传统终端的宽度，比如 vi 编译器）。由于屏幕尺寸和代码阅读终端的变化，现在的很多规范，开始使用 120 个字符的限制。所以我们编码的时候，需要留意一下；
• 如果一行不足以容纳一个表达式，就需要换行；
• 一般的换行原则包括以下五点。
  • 在逗号后换行。
  • 在操作符前换行。
  • 高级别的换行优先。
  • 新的换行与上一行同级别表达式的开头对齐。
  • 如果上述规则导致代码混乱或者代码太靠右，使用 8 个空格作为缩进（两个缩进单位）。

写好注释

几种常见注释类型

• 第一种类型，是记录源代码版权和授权的，一般放在每一个源文件的开头，说明源代码的版权所有者，以及授权使用的许可方式，或者其他的公共信息。
• 第二种类型，是用来生成用户文档的，比如 Java Doc。 这部分的作用，是用来生成独立的、不包含源代码的文档。 这些文档帮助使用者了解软件的功能和细节，主要面向的是该软件的使用者，而不是该软件的开发者。 比如 Java 的 API 规范的文档。
• 第三种类型，是用来解释源代码的。换句话说，就是帮助代码的阅读者理解代码。这是大家默认的注释类型。

三种风格的注释

• 针对第一种注释类型，也就是固定的版权和授权信息，使用一般的星号注释符（/-/）。注释块的首行和尾行只使用星号注释符，中间行以缩进一个空格的星号开始，文字和星号之间使用一个空格。注释的每行长度限制，和代码块的每行长度限制保持一致。
• 针对第二种注释类型，即生成用户文档的注释，使用 Javadoc 要求的格式，文档注释符（/-*/）。 除了首行使用特殊的文档注释符（/），其他的格式和第一种风格保持一致。
• 针对第三种注释类型，也就是代码解释注释，只使用行注释符（//）。 每行长度限制，和代码块的每行长度限制保持一致。

Code Tells You How, Comments Tell You Why.

写好声明的“八项纪律”

取一个好名字

• 既然是标识符，就涉及到取名字的问题。

一行一个声明

• 不推荐在同一行里声明多个变量，即使这一行很短。
  
• 不要在同一行声明不同类型的标识符。
  
• 表示数组的中括号“[]”是类型的一部分，而不是标识符的一部分。无论是 Java 语言，还是在 C 语言的代码中，都建议把数组符号放在类型该在的地方。
  

局部变量需要时再声明

• 标识符的声明应该和它的使用尽可能地靠近，特别是局部变量的标识符声明。这样在视觉上，标识符的定义和使用，可以方便我们阅读和记忆。
  

类属性要集中声明

• 同样是为了阅读和记忆，类变量的声明则要集中。因为类变量无论是私密变量，还是公开变量，在类的方法实现中，随时都可以调用。我们需要把这些变量放在一起，以便于修改和查找。
  

声明时就初始化

• 除非变量的初始值依赖于更多的条件，或者涉及到一定的计算，否则，声明时就应该完成初始化。声明时初始化，可以防止初始化的遗漏或者不必要的代码重复。
  

尾随的花括号

• 一般来说，类声明和方法声明后，要使用花括号把实现的代码包括进来。花括号的使用语法很随意。我不建议代码中混杂地使用不同的格式。推荐一种方法：
  • 左括号不要单独成行，要紧随在语句尾部，以一个空格隔开；
  • 右括号单独一行。
    

靠紧的小括号

• 小括号的使用语法也可以很随意。小括号一般用来识别一个标识符是不是方法标识符，所以建议小括号要紧靠着标识符，中间不要有空格。
  

搜索优化的换行

• 搜索优化是我们编写代码时要考虑的一个因素。搜索优化既包括针对搜索引擎的优化（SEO），也包括针对编辑器（vi, Netbeans）以及系统工具（grep）的搜索优化。
  
• 这些常用的搜索模式给了我们一个很好的启示：语义相关的词语，常见的搜索模式，要尽量放在用一行。
  

Java注解

Java 注解是 Java 1.5 引入的一个工具，类似于给代码贴个标签，通过注解可以为代码添加标签信息。这些标签信息可以添加在字段、方法和类上。开发工具、部署工具或者运行类库，可以对这些标签信息进行特殊的处理，从而获得更丰富的功能。注解已经成了 Java 生态系统一个非常重要的技术。使用注解可以大幅度降低我们的开发强度，提高工作效率，减少潜在的错误。像 Java 类库一样，注解也有了越来越丰富的定义和规范，成了我们需要掌握的重要技术之一。

• 这里只讨论编写规范的代码时，该怎么合理地使用注解，具体就是 Override、Deprecated、SuppressWarnings 这三个注解。更详细的 Java 注解技术和规范，以及如何自定义注解，需要你参考相关的文档。

你知道的越多，你不知道的越多。