Java编码规范

Chapter  1: General Principles(第一章 一般原则)

While it is important to write software that performs well, many other issues should concern the professional Java developer. All good software performs well. But great software, with written style, is predictable, robust, maintainable, supportable, and extensible.

尽管书写性能优异的程序很重要，但是专业的Java开发者还应关注许多其他的问题。所有优秀的程序都运行良好；可是具有（一定）书写风格的出色的程序，它们都具有可预测性、健壮性、可维护性、耐用性和可扩展性。（以下是作者的编码规范建议，译者）

1.   Adhere to the style of the original.（坚持原有代码的风格）

When modifying existing software, your changes should follow the style of the original code. Do not introduce a new coding style in a modification, and do not attempt to rewrite the old software just to make it match the new style. The use of different styles within a single source file produces code that is more difficult to read and comprehend. Rewriting old code simply to change its style may result in the introduction of costly yet avoidable defects.

当修改现有代码时，你的修改应该遵循源码的规范，既不要在修改中引入新的编码规范，更不要企图重写原始代码使之符合新的编码规范。在一个代码文件中使用多种编码风格（规范）是让人难于阅读和理解的；而重写代码使之符合新的规范则会引入高代价却无法避免的缺陷。

2.   Adhere to the Principle of Least Astonishment.（尽量符合习惯，不要制造震惊）

The Principle of Least Astonishment suggests you should avoid doing things that will surprise a user of your software. This implies the means of interaction and the behavior exhibited by your software must be predictable and consistent, and, if not, the documentation must clearly identify and justify any unusual patterns of use or behavior.

这个原则意味着，不要（在程序中）做使你的代码使用者吃惊的事。它还暗示：程序所展现出的交互手段和行为必须是可预测和一致的，即便没有达到这个要求，（那么）文档必须清晰明了的说明任何不常用的使用方式和行为。

To minimize the chances that a user will encounter something surprising in your software, you should emphasize the following characteristics in the design, implementation, and documentation of your Java software:

为了让代码的使用者少碰到些吃惊的事，必须在程序的设计、实现、文档中强调下述规范：

Simplicity     Build simple classes and simple methods. Determine how much you need to do to meet the expectations of your users.

简洁          建立尽量简单的类和方法满足用户需求。

Clarity        Ensure each class, interface, method, variable, and object has a clear purpose. Explain where, when, why, and how to use each.

清晰          确保每一个类、接口、方法、变量、对象都有明确的目的，说明它们在何处、何时使用，为什么使用以及怎样使用。

Completeness   Provide the minimum functionality that any reasonable user would expect to find and use. Create complete documentation; document all features and functionality.

完整          提供任何合理的代码使用者所预期的最小函数集；创建完整的文档，记录所有的特征和功用。

Consistency   Similar entities should look and behave the same; dissimilar entities should look and behave differently. Create and apply standards whenever possible.

一致          相似的实体其外观和行为也应相同；反之亦然。尽可能地创建和应用标准。

Robustness     Provide predictable documented behavior in response to errors and exceptions. Do not hide errors and do not force clients to detect errors.

健壮          提供可预测的程序出错和异常的文档说明。不要隐藏错误，也不要让使用者检测错误。

3.   Do it right the first time.（从现在做起）

Apply these rules to any code you write, not just code destined for production. More often than not, some piece of prototype or experimental code will make its way into a finished product, so you should anticipate this eventuality. Even if your code never makes it into production, someone else may still have to read it. Anyone who must look at your code will appreciate your professionalism and foresight at having consistently applied these rules from the start.

（现在）就应用这些规则到你的代码中去，而不仅仅应用在产品代码中。通常，一些原型或试验性质的代码被写入最终产品，因此，你必须预先处理这些可能发生的情况。即便你的代码不会进入产品，但也许其他人会阅读它们。一旦你从现在就保持应用这些规则，那些不得不浏览你的代码的人将会感激你的专业和远见。

4.   Document any deviations.（记录任何与规则相违背之处）

No standard is perfect and no standard is universally applicable. Sometimes you will find yourself in a situation where you need to deviate from an established standard.

没有完美无缺的标准，也没有四海皆准的规范。有时，你会发现你需要背离（放弃）一些标准。

Before you decide to ignore a rule, you should first make sure you understand why the rule exists and what the consequences are if it is not applied. If you decide you must violate a rule, then document why you have done so.

在你决定略过一条规则之前，你必须确保你已了解这条规则的意义以及省略它的后果。如果你确定要违背一条规则，就记录下你这么做的理由。

This is the prime directive.

以上是最基本的准则。