编程和文档约定的编写技巧（Java）

编程和文档约定

总结的一些重要且有用的 Java 编程和文档约定，此篇博客包含以下几个内容：
· 一般的命名和大小写约定
· 可移植性的技巧和约定

命名和大小写约定

1. 包
公开可见的包通常要尽量使用唯一的包名。十分常见的做法是，把网站的域名倒置，放在包名前（例如：com.oreilly.javanutshell)。所有的包名都应该使用小写字母。
如果包只在 应用内部使用，而且打包成 JAR 文件分发，那么这种包公开不可见，无需遵守上述约定，此时经常使用应用的名称做包名或包名的前缀

2. 引用类型
类型的名称应该以大写字母开头，而且要混用大小写（例如 String），如果类名包含多个单词，每个单词的第一个字母都要大写（例如 StringBuffer）。如果类型名称或类型名称中有一部分是简称，那么简称可以全用大写字母（例如 URL 和 HTMLParser）
类和枚举是为了表示对象，因此类名要使用名词（例如 Thread，Teapot 和 FormatConverter）

如果接口是用来为实现这个接口类提供额外信息的。那么一般应该使用形容词命名这个接口（例如 Runnable, Cloneable 和 Serializable）。注解类型一般也使用这种命名方式

如果接口的作用更像是抽象超类，那么应该使用名词命名（例如 Document，FileNameMap 和 Collection）

3. 方法
方法名始终以小写字母开头，如果方法名包含多个单词，除第一个单词外，其他单词的第一个字母都要大写（例如 insert（），insertObject（） 和 insertObjectAct（））。这种命名方式一般称为驼峰式命名

方法名一般都通过精细挑选，让第一个单词为动词，为了清楚表明方法的作用，方法名的长度不限，但应该尽量选择简短的名称，应该避免使用太通用的方法名，例如：performAction（），go（）或者doit（）

4. 字段和常量
非常量字段的名称使用的大小学约定和方法名一样，如果声明为 static final 的常量，其名称应该使用全大写形式，如果常量的名称包含多个单词，单词之间应该使用下划线分隔例如（MAX_VALUE），为字段选择的名称，应该最能说明字段或其值得作用。枚举类型定义的常量往往也全部使用大写字母

5. 参数
方法的参数使用的大小写约定和非常量字段一样，方法的参数名会出现在方法的文档中，因此应该选择一个能尽量清楚表明参数作用的名称，尽量使用一个单词命名参数，并在所有用到这个参数的地方使用相同的名称，例如，如果 widgeProcessor 类定义的方法中，有多个方法的第一个参数都是一个 widget 对象，那么在每个方法中可以都把这个参数命名为 widge 或 w

6. 局部变量
局部变量的名称是实现细节，在类外部不可见，尽管如此，选择一个好的名称会让代码变得更加容易阅读，理解，维护。变量的命名方式往往与方法和字段的命名约定一样。

实用的命名方式

为结构起的名字十分重要。向同组或是其他组表达我们的抽象构思时，命名就是一个关键。把软件构思从一个人的脑子中转移到另一个人的头脑中很难，多数情况下，比转移到实现构思的机器中还要难，所以我们需要竭尽所能把整个过程变得简单易行，审查人员应当十分留意代码中使用的名称。

当我们在进行命名时需要明确以下几个点：
—— 类型的名称能否表明类型的作用
—— 各个方法所做的事情是否完全和方法名表达的意思一致？ 理想情况下，应该不多也不少。
—— 名称的表达是否到位？是否需要换成更为具体的名称
—— 名称是否适用于所描述的领域
—— 同一领域中使用的名称是否一致
—— 名称中是否混杂着隐喻
—— 名称中是否重用了软件工程常用的术语

最重要的是：
你要对编写的代码能存活多久有个理性的认识。例如：银行的风险计算系统可能要使用十年或更久，而初创项目的圆形可能只会存在几周时间。因此，你要根据代码的生存时间相应的编写文档，代码存在的时间越长，文档就要写的越好。

…后续更新