好的JAVA风格

　　 caiyi0903（翻译）
　　
　　介绍
　　
　　作为一个已经工作了很多年的软件开发者和咨询师，我看过大量形形色色的程序语言代码。其中有文雅的也有丑陋的，但是不幸的是，它们中大多数代码都是丑陋的。 我希望能够说服你们，我的开发伙伴们，我们应该足够的重视我们的代码风格，尤其是那些在应用程序中提供用户接口和其他可视化部分的代码。在这两部分系列的第一部分， 我会解释为什么我们应该关心我们的代码外观，然后阐述一些好的Java风格的一般要素。
　　
　　为什么代码很重要
　　
　　尽管JAVA是用来写程序而不是散文， 但它仍然被用来表达思想和观点的。而且，在调查中显示，那些思想和观点在实际中完成了很多事情。为编写出好的JAVA风格而担忧，似乎是在浪费时间， 但实际上它对我们编写程序是很适宜的，因为它所要表达的思想和观点是格外清楚的。
　　
　　这里提供一些理由，为什么要使用好的JAVA代码规范
　　
　　一个软件产品的80%的生命期是在维护（maintenance）。
　　几乎没有一个软件在它的整个生命期里都是被它的作者来维护的。
　　使用好的风格提高了软件的可维护性。　
　　假如源代码和软件产品是捆绑给客户的，作为产品的剩余部分，它应该有好的分包（well-packaged），足够清楚和专业的代码。
　　
　　使用好的风格编写代码有以下几点好处：
　　
　　提高了代码的可读性，持续性，和谐性。这些都能使代码能更轻易的理解和维护。
　　使代码更轻易被跟踪和调试，因为它是清楚的和持续的。
　　使你或另一个程序员在编写终止时更轻易再继续下去，尤其在一个很长的时间后。
　　增加了代码预排（walkthroughs）的好处， 因为能让参入者更多的将焦点集中在代码正在做什么。
　　
　　概要方针
　　
　　使用好的JAVA风格并不困难， 但是它确实需要注重细节。下面是一些常用的概要指导方针：
　　
　　使代码更清楚和更轻易读　
　　使代码更持续　
　　使用显而易见的标识符名　
　　逻辑地组织你的文件和类　
　　每个文件只有一个类(这里不包括一些内部类)
　　使用80-90个字符的最大行宽　
　　明智的使用空格来and/or其他分隔符
　　缩排上，使用空格（Space）来代替Tab
　　
　　Tabs vs. 空格
　　在编写代码时，“Tabs vs. 空格” 是一个严谨的观点。这里我并不是暗示只有一个正确的方法。我支持使用空格，因为它能保证我的代码在你的编辑器里和我的编辑器里看到的相同，反之矣然。假如你感觉使用空格来代替Tab"不是正确的", 那么就使用Tab吧。
　　
　　括号和缩进
　　在编写代码时，缩进风格(cf., Raymond, "Indent Style")，或者放置括号("{" 和 "}") 和一些相关联的缩进代码，是另一个严谨的观点。象JAVA一样，有许多C风格的语言存在。我这里也不是暗示它们中哪一个更优先更好。在大多数本文的范例代码中，我使用了K&R 风格，假如你不喜欢K&R风格，那么就使用其他风格吧。
　　
　　注释
　　在JAVA代码中你可以使用两种注释： Javadoc 注释 (也称为文档注释) 和执行注释。 Javadoc注释能够被javadoc工具解压来制造一个API文档。执行注释是那些解释代码目的和方式的注释。在注释你的JAVA代码时请使用以下方针：
　　
　　
　　尽可能的使用Javadoc注释(在类和方法上，使之能最小化).
　　多使用块注释，少使用//注释, 除非一些非凡的情况，如变量声明
　　要记住：好注释是有帮助的，坏注释是麻烦的。
　　
　　Example 1. Bad Comment Style
　　
　　 // applyRotAscii() -- Apply ASCII ROT
　　　 private void applyRotAscii(){
　　　try{
　　 int rotLength = Integer.parseInt(rotationLengthField.getText().trim()); // get rot len
　　 RotAscii cipher = new RotAscii(rotLength); // new cipher
　　 textArea.setText(cipher.transform(textArea.getText())); // transform
　　　}catch(Exception ex){
　　 /* Show exception */
　　 ExceptionDialog.show(this, "Invalid rotation length: ", ex); }
　　　 }
　　
　　
　　
　　Example 2. Good Comment Style
　　
　　 /**
　　* Apply the ASCII rotation cipher to the user's text. The length is retrieved
　　* from the rotation length field, and the user's text is retrieved from the
　　* text area.
　　*
　　* @author Thornton Rose
　　*/
　　　 private void applyRotAscii() {
　　　int　　　rotLength = 0;　// rotation length
　　　RotAscii cipher = null;　// ASCII rotation cipher
　　　
　　　try {
　　 // Get rotation length field and convert to integer.
　　　
　　 rotLength = Integer.parseInt(rotationLengthField.getText().trim());
　　
　　 // Create ASCII rotation cipher and transform the user's text with it.
　　　
　　 cipher = new RotAscii(rotLength);
　　 textArea.setText(cipher.transform(textArea.getText()));
　　　
　　　 } catch(Exception ex) {
　　 // Report the exception to the user.
　　
　　 ExceptionDialog.show(this, "Invalid rotation length: ", ex);
　　　}
　　　 }
　　
　　块和语句
　　
　　使用下面的方针来编写块和语句：
　　
　　一行只写一个语句　
　　控制语句总是使用{}这样的括号 (e.g., 'if').
　　考虑在块的末尾使用一个注释 (e.g., } // end if), 尤其是长的或嵌套块
　　在块的开头放置变量的声明语句　
　　总记得初始化变量　
　　假如你是个完美主义者，左对齐变量名
　　在switch块里缩进case从句　
　　在操作符后留有空白
　　在if, for, 或while语句中， 在括号“（”前留有空白
　　在表达式中使用空白和插入语来增强可读性
　　
　　在for循环中的变量是个例外。 循环变量可能会在语句初始化部分被定义。 e.g., for (int i = 0; ...)
　　
　　.
　　
　　在块的末尾插入注释有助于你无意中跟踪到被删除的结尾括号“}”.
　　
　　Example 3. Bad Block Style.
　　
　　try{
　　　for(int i=0;i <5;i++){
　　 ...
　　 }
　　　int threshold=calculateThreshold();
　　　float variance=(threshold*2.8)-1;
　　　int c=0;
　　　if (threshold <=15) c=calculateCoefficient();
　　　switch(c){
　　　case 1: setCeiling(c*2); break;
　　　case 2: setCeiling(c*3); break;
　　　else: freakOut();
　　　}
　　　 }catch(Exception ex){ ... }
　　
　　Example 4. Good Block Style.
　　
　　 try {
　　　int　 threshold　= 0;
　　　float variance　　= 0.0;
　　　int　 coefficient = 0;
　　　
　　　// Prepare 5 cycles.
　　　
　　
　　　for (int i = 0; i　< 5; i ++){
　　 prepareCycle(i);
　　　}
　　　
　　　// Calculate the threshold and variance.
　　　
　　　threshold = calculateThreshold();
　　　variance = (threshold * 2.8) - 1;
　　　
　　　// If the threshold is less than the maximum, calculate the coefficient.
　　　// Otherwise, throw an exception.
　　　
　　　if (threshold　<= MAX_THRESHOLD) {
　　 coefficient = calculateCoefficient();
　　　} else {
　　 throw new RuntimeException("Threshold exceeded!");
　　　}
　　　
　　　// Set the ceiling based on the coefficient.
　　　
　　　switch (coefficient) {
　　 case 1:
　　setCeiling(coefficient * 2);
　　break;
　　　
　　 case 2:
　　setCeiling(coefficient * 3);
　　break;
　　　
　　 else:
　　freakOut();
　　　} // end switch
　　　 } catch(Exception ex) {
　　　...
　　　 } // end try