Changes between Initial Version and Version 1 of standard


Ignore:
Timestamp:
04/28/2012 10:30:09 AM (14 years ago)
Author:
lifeng
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • standard

    v1 v1  
     1== '''前言''' == 
     2本规范由编程原则组成，融合并提炼了开发人员长时间积累下来的成熟经验，意在帮助形成良好一致的编程风格。 
     3== '''适用范围''' == 
     4如无特殊说明，以下规则要求完全适用于BBS项目，同时也可大部分适用于太平洋网络旗下其他Java项目。 
     5 
     6== '''标准化的重要性和好处''' == 
     7当一个软件项目尝试着遵守公共一致的标准时，可以使参与项目的开发人员更容易了解项目中的代码、弄清程序的状况。使新的参与者可以很快的适应环境，防止部分参与者出于节省时间的需要，自创一套风格并养成终生的习惯，导致其它人在阅读时浪费过多的时间和精力。而且在一致的环境下，也可以减少编码出错的机会。缺陷是由于每个人的标准不同，所以需要一段时间来适应和改变自己的编码风格，暂时性的降底了工作效率。从使项目长远健康的发展以及后期更高的团队工作效率来考虑暂时的工作效率降低是值得的，也是必须要经过的一个过程。标准不是项目成功的关键，但可以帮助我们在团队协作中有更高的效率并且更加顺利的完成既定的任务。 
     8* '''一个软件的生命周期中，80%的花费在于维护''' 
     9* '''几乎没有任何一个软件，在其整个生命周期中，均由最初的开发人员来维护''' 
     10* '''编码规范可以改善软件的可读性，可以让程序员尽快而彻底地理解新的代码''' 
     11* '''新人可以很快的适应环境''' 
     12* '''防止新接触Java的人出于节省时间的需要，自创一套风格并养成终生的习惯''' 
     13* '''防止新接触Java的人一次次的犯同样的错误''' 
     14* '''在一致的环境下，人们可以减少犯错的机会''' 
     15为了执行规范，每个软件开发人员必须一致遵守编码规范。'''每个人。''' 
     16 
     17== '''Java编码规范与原则''' == 
     18===Java源文件=== 
     19:每个Java源文件都包含一个单一的公共类或接口。若私有类和接口与一个公共类相关联，可以将它们和公共类放入同一个源文件。公共类必须是这个文件中的第一个类或接口。 
     20====开头注释==== 
     21:所有的源文件都应该在开头有一个C语言风格的注释，其中列出类名、版本信息、日期和版权声明： 
     22<pre> 
     23  /* 
     24   * Classname 
     25   * Version information 
     26   * Date 
     27   * Copyright notice 
     28   */ 
     29</pre> 
     30====包和引入语句==== 
     31:在多数Java源文件中，第一个非注释行是包语句。在它之后可以跟引入语句。例如： 
     32<pre> 
     33  package java.awt; 
     34 
     35  import java.awt.peer.CanvasPeer; 
     36</pre> 
     37====类和接口声明==== 
     38===注释=== 
     39:*Java程序有两类注释：'''实现注释'''(implementation comments)和'''文档注释'''(document comments)。'''实现注释'''是那些在C++中见过的，使用/*...*/和//界定的注释。'''文档注释'''(被称为"doc comments")是Java独有的，并由/**...*/界定。文档注释可以通过javadoc工具转换成HTML文件。实现注释用以注释代码或者实现细节。文档注释从实现自由(implementation-free)的角度描述代码的规范。它可以被那些手头没有源码的开发人员读懂。 
     40:*注释应被用来给出代码的总括，并提供代码自身没有提供的附加信息。注释应该仅包含与阅读和理解程序有关的信息。例如，相应的包如何被建立或位于哪个目录下之类的信息不应包括在注释中。 
     41:*在注释里，对设计决策中重要的或者不是显而易见的地方进行说明是可以的，但应避免提供代码中己清晰表达出来的重复信息。多余的的注释很容易过时。通常应避免那些代码更新就可能过时的注释。 
     42:*'''注意：频繁的注释有时反映出代码的低质量。当你觉得被迫要加注释的时候，考虑一下重写代码使其更清晰。''' 
     43:*注释不应写在用星号或其他字符画出来的大框里。注释不应包括诸如制表符和回退符之类的特殊字符。 
     44:*程序开发中难免留下一些临时代码和调试代码，此类代码必须添加注释，以免日后遗忘。所有临时性、调试性、试验性的代码，必须添加统一的注释标记“//debug”并后跟完整的注释信息，这样可以方便在程序发布和最终调试前批量检查程序中是否还存在有疑问的代码。例如： 
     45<pre> 
     46int num = 1; 
     47boolean flag = true;      //debug 这里不能确定是否需要对flag进行赋值 
     48if(flag) { 
     49     //Statements 
     50} 
     51 
     52</pre> 
     53====实现注释的格式==== 
     54:程序可以有4种实现注释的风格：块(block)、单行(single-line)、尾端(trailing)和行末(end-of-line)。 
     55=====块注释===== 
     56:块注释通常用于提供对文件，方法，数据结构和算法的描述。块注释被置于每个文件的开始处以及每个方法之前。它们也可以被用于其他地方，比如方法内部。在功能和方法内部的块注释应该和它们所描述的代码具有一样的缩进格式。 
     57:块注释之首应该有一个空行，用于把块注释和代码分割开来，比如： 
     58<pre> 
     59 
     60  /* 
     61   * Here is a block comment. 
     62   */ 
     63</pre> 
     64=====单行注释===== 
     65:短注释可以显示在一行内，并与其后的代码具有一样的缩进层级。如果一个注释不能在一行内写完，就该采用块注释(参见"块注释")。单行注释之前应该有一个空行。以下是一个Java代码中单行注释的例子： 
     66<pre> 
     67  if (condition) { 
     68 
     69    /* Handle the condition. */ 
     70    ... 
     71  } 
     72</pre> 
     73=====尾端注释===== 
     74:极短的注释可以与它们所要描述的代码位于同一行，但是应该有足够的空白来分开代码和注释。若有多个短注释出现于大段代码中，它们应该具有相同的缩进。以下是一个Java代码中尾端注释的例子： 
     75<pre> 
     76  if (a == 2) { 
     77      return TRUE;              /* special case */ 
     78  } else { 
     79      return isPrime(a);         /* works only for odd a */ 
     80  } 
     81</pre> 
     82=====行末注释===== 
     83:注释界定符"//"，可以注释掉整行或者一行中的一部分。它一般不用于连续多行的注释文本；然而，它可以用来注释掉连续多行的代码段。以下是所有三种风格的例子： 
     84<pre> 
     85  if (foo > 1) { 
     86 
     87      // Do a double-flip. 
     88      ... 
     89  } 
     90  else { 
     91      return false;          // Explain why here. 
     92  } 
     93 
     94  //if (bar > 1) { 
     95  // 
     96  //    // Do a triple-flip. 
     97  //    ... 
     98  //} 
     99  //else { 
     100  //    return false; 
     101  //} 
     102</pre> 
     103====文档注释==== 
     104:文档注释描述Java的类、接口、构造器，方法，以及字段(field)。每个文档注释都会被置于注释定界符/**...*/之中，一个注释对应一个类、接口或成员。该注释应位于声明之前： 
     105<pre> 
     106  /** 
     107    * The Example class provides ... 
     108    */ 
     109  public class Example { ... 
     110</pre>       
     111:*注意顶层的类和接口是不缩进的，而其成员是缩进的。描述类和接口的文档注释的第一行(/**)不需缩进；随后的文档注释每行都缩进1格(使星号纵向对齐)。成员，包括构造函数在内，其文档注释的第一行缩进4格，随后每行都缩进5格。 
     112:*若你想给出有关类、接口、变量或方法的信息，而这些信息又不适合写在文档中，则可使用实现块注释或紧跟在声明后面的单行注释。例如，有关一个类实现的细节，应放入紧跟在类声明后面的实现块注释中，而不是放在文档注释中。 
     113:*文档注释不能放在一个方法或构造器的定义块中，因为Java会将位于文档注释之后的第一个声明与其相关联。 
     114 
     115===声明=== 
     116====每行声明变量的数量==== 
     117:推荐一行一个声明，因为这样以利于写注释。亦即， 
     118<pre> 
     119  int level;  // indentation level 
     120  int size;   // size of table 
     121</pre> 
     122:要优于， 
     123<pre> 
     124  int level, size; 
     125</pre> 
     126:不要将不同类型变量的声明放在同一行，例如： 
     127<pre> 
     128  int foo,  fooarray[];   //WRONG! 
     129</pre>       
     130:注意：上面的例子中，在类型和标识符之间放了一个空格，另一种被允许的替代方式是使用制表符： 
     131<pre> 
     132  int          level;         // indentation level 
     133  int          size;          // size of table 
     134  Object     currentEntry;  // currently selected table entry 
     135</pre> 
     136====初始化==== 
     137:尽量在声明局部变量的同时初始化。唯一不这么做的理由是变量的初始值依赖于某些先前发生的计算。 
     138====布局==== 
     139:只在代码块的开始处声明变量。（一个块是指任何被包含在大括号"{"和"}"中间的代码。）不要在首次用到该变量时才声明之。这会把注意力不集中的程序员搞糊涂，同时会妨碍代码在该作用域内的可移植性。 
     140<pre> 
     141  void myMethod() { 
     142      int int1 = 0;         // beginning of method block 
     143 
     144      if (condition) { 
     145          int int2 = 0;     // beginning of "if" block 
     146          ... 
     147      } 
     148  } 
     149</pre>       
     150:该规则的一个例外是for循环的索引变量 
     151<pre> 
     152  for (int i = 0; i < maxLoops; i++) { ... } 
     153</pre>       
     154:避免声明的局部变量覆盖上一级声明的变量。例如，不要在内部代码块中声明相同的变量名： 
     155<pre> 
     156  int count; 
     157  ... 
     158  myMethod() { 
     159      if (condition) { 
     160          int count = 0;     // AVOID! 
     161          ... 
     162      } 
     163      ... 
     164  } 
     165</pre> 
     166====类和接口的声明==== 
     167:当编写类和接口是，应该遵守以下格式规则： 
     168:*在方法名与其参数列表之前的左括号"("间不要有空格 
     169:*左大括号"{"位于声明语句同行的末尾 
     170:*右大括号"}"另起一行，与相应的声明语句对齐，除非是一个空语句，"}"应紧跟在"{"之后 
     171<pre> 
     172  class Sample extends Object { 
     173      int ivar1; 
     174      int ivar2; 
     175 
     176      Sample(int i, int j) { 
     177          ivar1 = i; 
     178          ivar2 = j; 
     179      } 
     180 
     181      int emptyMethod() {} 
     182 
     183      ... 
     184  } 
     185</pre> 
     186:*方法与方法之间以空行分隔 
     187 
     188===语句=== 
     189====简单语句==== 
     190:每行至多包含一条语句，例如： 
     191<pre> 
     192  argv++;       // 正确 
     193  argc--;       // 正确 
     194  argv++; argc--;       // 避免 
     195</pre>       
     196====复合语句==== 
     197:复合语句是包含在大括号中的语句序列，形如"{ 语句 }"。 
     198:*被括其中的语句应该较之复合语句缩进一个层次。 
     199:*左大括号"{"应位于复合语句起始行的行尾；右大括号"}"应另起一行并与复合语句首行对齐。 
     200:*大括号可以被用于所有语句，包括单个语句，只要这些语句是诸如if-else或for控制结构的一部分。这样便于添加语句而无需担心由于忘了加括号而引入bug。 
     201====返回语句==== 
     202:一个带返回值的return语句不使用小括号"()"，除非它们以某种方式使返回值更为显见。例如： 
     203<pre> 
     204  return; 
     205 
     206  return myDisk.size(); 
     207 
     208  return (size ? size : defaultSize); 
     209</pre> 
     210====if语句==== 
     211:if结构中，else和elseif与前后两个大括号同行，左右各一个空格。另外，即便if后只有一行语句，仍然需要加入大括号，以保证结构清晰； if-else语句应该具有如下格式： 
     212<pre> 
     213  if (condition) { 
     214      statements; 
     215  } 
     216 
     217  if (condition) { 
     218      statements; 
     219  } else { 
     220      statements; 
     221  } 
     222 
     223  if (condition) { 
     224      statements; 
     225  } else if (condition) { 
     226      statements; 
     227  } else{ 
     228      statements; 
     229  } 
     230</pre>       
     231:'''注意：if语句总是用"{"和"}"括起来，避免使用如下容易引起错误的格式：''' 
     232<pre> 
     233  if (condition) //AVOID! THIS OMITS THE BRACES {}! 
     234      statement; 
     235</pre> 
     236 
     237====for语句==== 
     238:一个for语句应该具有如下格式： 
     239<pre> 
     240  for (initialization; condition; update) { 
     241      statements; 
     242  } 
     243</pre> 
     244:一个空的for语句(所有工作都在初始化，条件判断，更新子句中完成）应该具有如下格式： 
     245<pre> 
     246  for (initialization; condition; update); 
     247</pre>       
     248:当在for语句的初始化或更新子句中使用逗号时，避免因使用三个以上变量，而导致复杂度提高。若需要，可以在for循环之前(为初始化子句)或for循环末尾(为更新子句)使用单独的语句。 
     249====while语句==== 
     250:一个while语句应该具有如下格式 
     251<pre> 
     252  while (condition) { 
     253      statements; 
     254  } 
     255</pre>       
     256:一个空的while语句应该具有如下格式： 
     257<pre> 
     258  while (condition); 
     259</pre> 
     260====do-while语句==== 
     261:一个do-while语句应该具有如下格式： 
     262<pre> 
     263  do { 
     264      statements; 
     265  } while (condition); 
     266</pre> 
     267 
     268====switch语句==== 
     269:switch结构中，通常当一个case块处理后，将跳过之后的case块处理，因此大多数情况下需要添加break。break的位置视程序逻辑，与case同在一行，或新起一行均可，但同一switch体中，break的位置格式应当保持一致。 
     270:一个switch语句应该具有如下格式： 
     271<pre> 
     272  switch (condition) { 
     273  case ABC: 
     274      statements; 
     275      /* falls through */ 
     276  case DEF: 
     277      statements; 
     278      break; 
     279 
     280  case XYZ: 
     281      statements; 
     282      break; 
     283 
     284  default: 
     285      statements; 
     286      break; 
     287  }       
     288</pre> 
     289:每当一个case顺着往下执行时(因为没有break语句)，通常应在break语句的位置添加注释。上面的示例代码中就包含注释/* falls through */。 
     290 
     291====try-catch语句==== 
     292:一个try-catch语句应该具有如下格式： 
     293<pre> 
     294  try { 
     295      statements; 
     296  } catch (ExceptionClass e) { 
     297      statements; 
     298  } 
     299</pre>       
     300:一个try-catch语句后面也可能跟着一个finally语句，不论try代码块是否顺利执行完，它都会被执行。 
     301<pre> 
     302  try { 
     303      statements; 
     304  } catch (ExceptionClass e) { 
     305      statements; 
     306  } finally { 
     307      statements; 
     308  } 
     309</pre> 
     310 
     311===空白=== 
     312====空行==== 
     313:空行将逻辑相关的代码段分隔开，以提高可读性。 
     314:下列情况应该总是使用两个空行： 
     315:*一个源文件的两个片段(section)之间 
     316:*类声明和接口声明之间 
     317:下列情况应该总是使用一个空行： 
     318:*两个方法之间 
     319:*方法内的局部变量和方法的第一条语句之间 
     320:*块注释或单行注释之前 
     321:*一个方法内的两个逻辑段之间，用以提高可读性 
     322====空格==== 
     323:下列情况应该使用空格： 
     324:*一个紧跟着括号的关键字应该被空格分开，例如： 
     325<pre> 
     326  while (true) { 
     327      ... 
     328  } 
     329</pre>  
     330:'''注意：空格不应该置于方法名与其左括号之间。这将有助于区分关键字和方法调用。''' 
     331:*空白应该位于参数列表中逗号的后面 
     332:*所有的二元运算符，除了"."，应该使用空格将之与操作数分开。一元操作符和操作数之间不因该加空格，比如：负号("-")、自增("++")和自减("--")。例如： 
     333<pre> 
     334    a += c + d; 
     335    a = (a + b) / (c * d); 
     336 
     337    while (d++ = s++) { 
     338        n++; 
     339    } 
     340    printSize("size is " + foo + "\n"); 
     341</pre>  
     342:*for语句中的表达式应该被空格分开，例如： 
     343<pre> 
     344    for (expr1; expr2; expr3) 
     345</pre>       
     346:*强制转型后应该跟一个空格，例如： 
     347<pre> 
     348    myMethod((byte) aNum, (Object) x); 
     349    myMethod((int) (cp + 5), ((int) (i + 3)) + 1); 
     350</pre> 
     351 
     352===命名规范=== 
     353:*命名规范使程序更易读，从而更易于理解。它们也可以提供一些有关标识符功能的信息，以助于理解代码，例如，不论它是一个常量，包，还是类。命名是程序规划的核心。古人相信只要知道一个人真正的名字就会获得凌驾于那个人之上的不可思议的力量。只要你给事物想到正确的名字，就会给你以及后来的人带来比代码更强的力量。 
     354:*名字就是事物在它所处的生态环境中一个长久而深远的结果。总的来说，只有了解系统的程序员才能为系统取出最合适的名字。如果所有的命名都与其自然相适合，则关系清晰，含义可以推导得出，一般人的推想也能在意料之中。 
     355:*就一般约定而言，类、函数和变量的名字应该总是能够描述让代码阅读者能够容易的知道这些代码的作用。形式越简单、越有规则，就越容易让人感知和理解。应该避免使用模棱两可，晦涩不标准的命名。 
     356:*以标准计算机英文为蓝本，杜绝一切拼音、或拼音英文混杂的命名方式。 
     357:*可以合理的对过长的命名进行缩写，例如bio(biography)，tpp(threadsPerPage)，前提是英文中有这样既有的缩写形式，或字母符合英文缩写规范。 
     358:*必须清楚所使用英文单词的词性，在权限相关的范围内，大多使用allow***或is***的形式，前者后面接动词，后者后面接形容词。 
     359====包==== 
     360:一个唯一包名的前缀总是全部小写的ASCII字母并且是一个顶级域名，通常是com，edu，gov，mil，net，org，或1981年ISO 3166标准所指定的标识国家的英文双字符代码。包名的后续部分根据不同机构各自内部的命名规范而不尽相同。这类命名规范可能以特定目录名的组成来区分部门(department)，项目(project)，机器(machine)，或注册名(login names)。      
     361<pre> 
     362com.sun.eng 
     363com.apple.quicktime.v2 
     364edu.cmu.cs.bovik.cheese 
     365</pre> 
     366====类==== 
     367:类名是个一名词，采用大小写混合的方式，每个单词的首字母大写。尽量使你的类名简洁而富于描述。使用完整单词，避免缩写词(除非该缩写词被更广泛使用，像URL，HTML) 
     368<pre> 
     369class Raster; 
     370class ImageSprite; 
     371</pre> 
     372====接口==== 
     373:大小写规则与类名相似 
     374<pre> 
     375interface RasterDelegate; 
     376interface Storing; 
     377</pre> 
     378====方法==== 
     379:方法名是一个动词，采用大小写混合的方式，第一个单词的首字母小写，其后单词的首字母大写。      
     380<pre> 
     381run(); 
     382runFast(); 
     383getBackground(); 
     384</pre> 
     385====变量==== 
     386:除了变量名外，所有实例，包括类，类常量，均采用大小写混合的方式，第一个单词的首字母小写，其后单词的首字母大写。变量名不应以下划线或美元符号开头，尽管这在语法上是允许的。 
     387:变量命名只能使用项目中有据可查的英文缩写方式，例如可以使用data而不可使用data1、data2这样容易产生混淆的形式，应当使用threadData、postData这样一目了然容易理解的形式。 
     388:'''变量名应简短且富于描述。'''变量名的选用应该易于记忆，即，能够指出其用途。尽量避免单个字符的变量名，除非是一次性的临时变量。临时变量通常被取名为i，j，k，m和n，它们一般用于整型；c，d，e，它们一般用于字符型。 
     389<pre> 
     390char c; 
     391int i; 
     392float myWidth; 
     393</pre> 
     394====实例变量==== 
     395:大小写规则和变量名相似，除了前面需要一个下划线      
     396<pre> 
     397int _employeeId; 
     398String _name; 
     399Customer _customer; 
     400</pre> 
     401====常量==== 
     402:类常量和ANSI常量的声明，应该全部大写，单词间用下划线隔开。(尽量避免ANSI常量，容易引起错误) 
     403<pre> 
     404static final int MIN_WIDTH = 4; 
     405static final int MAX_WIDTH = 999; 
     406static final int GET_THE_CPU = 1; 
     407</pre> 
     408 
     409===编程惯例=== 
     410====访问控制==== 
     411:若没有足够理由，不要把实例或类变量声明为公有。通常，实例变量无需显式的设置(set)和获取(get)，通常这作为方法调用的边缘效应 (side effect)而产生。 
     412:一个具有公有实例变量的恰当例子，是类仅作为数据结构，没有行为。亦即，若你要使用一个结构(struct)而非一个类(如果java支持结构的话)，那么把类的实例变量声明为公有是合适的。 
     413 
     414====引用类变量和类方法==== 
     415避免用一个对象访问一个类的静态变量和方法。应该用类名替代。例如： 
     416<pre> 
     417  classMethod();             //正确 
     418  AClass.classMethod();      //正确 
     419  anObject.classMethod();    //避免 
     420</pre>       
     421====常量==== 
     422:位于for循环中作为计数器值的数字常量，除了-1,0和1之外，不应被直接写入代码。 
     423====变量赋值==== 
     424避免在一个语句中给多个变量赋相同的值。它很难读懂。例如： 
     425<pre> 
     426  fooBar.fChar = barFoo.lchar = 'c'; // 避免 
     427</pre>       
     428:不要将赋值运算符用在容易与相等关系运算符混淆的地方。例如： 
     429<pre> 
     430  if (c++ = d++) {        //避免 
     431      ... 
     432  } 
     433</pre>       
     434:应该写成 
     435<pre> 
     436  if ((c++ = d++) != 0) { 
     437    ... 
     438  } 
     439</pre>       
     440:不要使用内嵌(embedded)赋值运算符试图提高运行时的效率，这是编译器的工作。例如： 
     441<pre> 
     442  d = (a = b + c) + r;        // 避免 
     443</pre>       
     444:应该写成 
     445<pre> 
     446  a = b + c; 
     447  d = a + r; 
     448</pre> 
     449====圆括号==== 
     450:一般而言，在含有多种运算符的表达式中使用圆括号来避免运算符优先级问题，是个好方法。即使运算符的优先级对你而言可能很清楚，但对其他人未必如此。你不能假设别的程序员和你一样清楚运算符的优先级。 
     451<pre> 
     452  if (a == b && c == d)     // 避免 
     453  if ((a == b) && (c == d))  // 正确 
     454</pre>       
     455====返回值==== 
     456:设法让你的程序结构符合目的。例如： 
     457<pre> 
     458  if (booleanExpression) { 
     459      return true; 
     460  } else { 
     461      return false; 
     462  } 
     463</pre>       
     464:应该代之以如下方法： 
     465<pre> 
     466  return booleanExpression; 
     467</pre>       
     468:类似地： 
     469<pre> 
     470  if (condition) { 
     471      return x; 
     472  } 
     473  return y; 
     474</pre>       
     475:应该写做： 
     476<pre> 
     477  return (condition ? x : y); 
     478</pre> 
     479====条件运算符"?"前的表达式==== 
     480:如果一个包含二元运算符的表达式出现在三元运算符" ? : "的"?"之前，那么应该给表达式添上一对圆括号。例如： 
     481<pre> 
     482  (x >= 0) ? x : -x; 
     483</pre> 
     484 
     485===书写规则=== 
     486====缩进==== 
     487:'''每个缩进的单位约定是一个TAB(4个空白字符宽度)'''，需每个参与项目的开发人员在编辑器(UltraEdit、EditPlus、Vim等)中进行强制设定，以防在编写代码时遗忘而造成格式上的不规范。 
     488:本缩进规范适用于Java、JavaScript中的函数、类、逻辑结构、循环等。 
     489====行长度==== 
     490:尽量避免一行的长度超过80个字符，因为很多终端和工具不能很好处理之。 
     491:'''注意：用于文档中的例子应该使用更短的行长，长度一般不超过70个字符。''' 
     492====换行==== 
     493:当一个表达式无法容纳在一行内时，可以依据如下一般规则断开之： 
     494:*在一个逗号后面断开 
     495:*在一个操作符前面断开 
     496:*宁可选择较高级别的断开，而非较低级别的断开 
     497:*新的一行应该与上一行同一级别表达式的开头处对齐 
     498:*如果以上规则导致你的代码混乱或者使你的代码都堆挤在右边，那就代之以缩进8个空格。以下是断开方法调用的一些例子： 
     499<pre> 
     500  someMethod(longExpression1, longExpression2, longExpression3, 
     501                   longExpression4, longExpression5); 
     502 
     503  var = someMethod1(longExpression1, 
     504                            someMethod2(longExpression2, 
     505                                               longExpression3)); 
     506</pre>  
     507:*以下是两个断开算术表达式的例子。前者更好，因为断开处位于括号表达式的外边，这是个较高级别的断开。 
     508<pre> 
     509  longName1 = longName2 * (longName3 + longName4 - longName5) 
     510                     + 4 * longname6; //推荐 
     511 
     512  longName1 = longName2 * (longName3 + longName4 
     513                                         - longName5) + 4 * longname6; //避免 
     514</pre>       
     515:*以下是两个缩进方法声明的例子。前者是常规情形。后者若使用常规的缩进方式将会使第二行和第三行移得很靠右，所以代之以缩进8个空格 
     516<pre> 
     517  //CONVENTIONAL INDENTATION 
     518  someMethod(int anArg, Object anotherArg, String yetAnotherArg, 
     519                    Object andStillAnother) { 
     520    ... 
     521  } 
     522 
     523  //INDENT 8 SPACES TO AVOID VERY DEEP INDENTS 
     524  private static synchronized horkingLongMethodName(int anArg, 
     525          Object anotherArg, String yetAnotherArg, 
     526          Object andStillAnother) { 
     527    ... 
     528  } 
     529</pre>       
     530:*if语句的换行通常使用8个空格的规则，因为常规缩进(4个空格)会使语句体看起来比较费劲。比如： 
     531<pre> 
     532  //不推荐 
     533  if ((condition1 && condition2) 
     534      || (condition3 && condition4) 
     535      ||!(condition5 && condition6)) { //错误的换行格式 
     536      doSomethingAboutIt();             //这行容易被忽视 
     537  } 
     538 
     539  //推荐用这种 
     540  if ((condition1 && condition2) 
     541          || (condition3 && condition4) 
     542          ||!(condition5 && condition6)) { 
     543      doSomethingAboutIt(); 
     544  } 
     545 
     546  //或者用这种 
     547  if ((condition1 && condition2) || (condition3 && condition4) 
     548          ||!(condition5 && condition6)) { 
     549      doSomethingAboutIt(); 
     550  } 
     551</pre>       
     552:*这里有三种可行的方法用于处理三元运算表达式： 
     553<pre> 
     554  alpha = (aLongBooleanExpression) ? beta : gamma; 
     555 
     556  alpha = (aLongBooleanExpression) ? beta 
     557                                   : gamma; 
     558 
     559  alpha = (aLongBooleanExpression) 
     560          ? beta 
     561          : gamma; 
     562</pre>       
     563====大括号{}==== 
     564:首括号与关键词同行，尾括号与关键字同列； 
     565 
     566====运算符、小括号、空格、关键词和函数==== 
     567:*每个运算符与两边参与运算的值或表达式中间要有一个空格，唯一的特例是字符连接运算符号两边不加空格； 
     568:*左括号“(” 应和函数关键词紧贴在一起，除此以外应当使用空格将“(”同前面内容分开； 
     569:*右括号“)”除后面是“)”或者“.”以外，其他一律用空格隔开它们； 
     570:*除字符串中特意需要，一般情况下，在程序以及HTML中不出现两个连续的空格； 
     571:*任何情况下，程序中不能出现空白的带有TAB或空格的行，即：这类空白行应当不包含任何TAB或空格。同时，任何程序行尾也不能出现多余的TAB或空格。多数编辑器具有自动去除行尾空格的功能，如果习惯养成不好，可临时使用它，避免多余空格产生； 
     572:*每段较大的程序体，上、下应当加入空白行，两个程序块之间只使用1个空行，禁止使用多行。 
     573:*程序块划分尽量合理，过大或者过小的分割都会影响他人对代码的阅读和理解。一般可以以较大函数定义、逻辑结构、功能结构来进行划分。少于15行的程序块，可不加上下空白行； 
     574:*说明或显示部分中，内容如含有中文、数字、英文单词混杂，应当在数字或者英文单词的前后加入空格。 
     575 
     576====函数定义==== 
     577:*参数的名字和变量的命名规范一致； 
     578:*函数定义中的左小括号，与函数名紧挨，中间无需空格； 
     579:*开始的左大括号与函数定义为同一行，中间加一个空格，不要另起一行； 
     580:*函数调用与定义的时候参数与参数之间加入一个空格； 
     581:*必须仔细检查并切实杜绝函数起始缩进位置与结束缩进位置不同的现象； 
     582 
     583:例如，符合标准的定义： 
     584<pre> 
     585public void authcode(String string, int operation, boolean flag) { 
     586     if(flag) { 
     587          //Statement 
     588     } 
     589     //函数体 
     590} 
     591</pre> 
     592:不符合标准的定义： 
     593<pre> 
     594public void authcode(String string,int operation,boolean flag) 
     595{ 
     596     //函数体 
     597} 
     598</pre> 
     599 
     600====提示语言问题==== 
     601:程序中直接写出的中文内容，应充分保证书面语的特征：语言通顺、简洁、得体、无歧义。应彻底杜绝认为直接写提示语言是临时性操作的想法，反复推敲，并总结之前提示语言的特征规范，加以应用。良好的语言文字表达能力，是每个优秀程序员必须具备的基本素质之一。 
     602 
     603===代码重用=== 
     604:代码的有效重用可以减少效率的损失与资源的浪费。在开发软件项目时为了避免重复劳动和浪费时间。开发人员应尽量提高现有代码的重用率，同时将更多的精力用在新技术的应用和新功能的创新开发上面。 
     605 
     606::*在需要多次使用代码，并且对于您希望实现的任务没有可用的内置函数时，不吝啬定义函数或类。开发者须根据功能、调用情况，将函数和类放置于相应的class中。超过3行，实现相同功能的程序切勿在不同程序中多次出现，这是无法容忍和回避的问题； 
     607::*在任何时候都不要出现同一个程序中出现两段或更多的相似代码或相同代码，即便在不同程序中，也应尽力避免。开发者应当总是有能力找到避免代码大段(超过10行)重复或类似的情况。 
     608 
     609:'''需要强调的是，本部分虽然篇幅较短，但却是十分需要经验，并将花费开发者大量时间和精力去进行优化的部分，任何产品开发者必须时刻清楚和理解代码重用的重要性和必要性，切实在增强产品效率、逻辑性和可读性上下功夫，这是一名优秀软件开发者所必须具备的基本素质。''' 
     610 
     611===Jsp相关问题=== 
     612====页面结构==== 
     613:*所有提供完整调用的Jsp页面的第一行都要以编码声明开头，用GBK编码； 
     614<pre> 
     615<%@ page contentType="text/html; charset=GBK" pageEncoding="GBK" %> 
     616</pre> 
     617:*Jsp的第二行要include一个公用的jspf，如果是接收输入数据的action页面，使用ajax-sys.jspf，其他则默认使用sys.jspf 
     618<pre> 
     619//默认include的jspf 
     620<%@ include file="WEB-INF/jspf/sys.jspf"%> 
     621 
     622//接收输入数据的action操作jsp使用的jspf 
     623<%@ include file="WEB-INF/jspf/ajax-sys.jspf"%> 
     624</pre> 
     625 
     626====Json输出==== 
     627:所有的Json输出都要用org.json包里面的类包装，不允许直接拼字符串方式输出。 
     628 
     629=数据库设计= 
     630==字段== 
     631===表和字段命名=== 
     632:表和字段的命名以前面《命名原则》的约定为基本准则。 
     633:所有数据表名称，只要其名称是可数名词，则必须以复数方式命名，例如：cdb_members(用户表)、cdb_posts(帖子表)；存储多项内容的字段，或代表数量的字段，也应当以复数方式命名，例如：params(parameters，自定义代码的参数个数)、views(查看次数)、replies(回复次数)。 
     634:当几个表间的字段有关连时，要注意表与表之间关联字段命名的统一，如cdb_threads表中的tid与cdb_posts表中的tid。 
     635:代表id自增量的字段，通常用以下几种形式： 
     636:*最常用的核心id，或经常在URL中进行调用的，尽量用简写的形式，例如tid、pid、uid； 
     637:*有功能性作用，URL中偶尔用到的id，使用全称的形式，例如pluginid； 
     638:*没有功能性作用，只为管理和维护方便而设的id，可以使用全称的形式，也可只将其命名为id。 
     639所有与表、字段相关的命名，请务必大量参考现有字段的命名方式，以保证命名的系统性和统一性。 
     640 
     641===字段结构=== 
     642:*允许NULL值的字段，数据库在进行比较操作时，会先判断其是否为NULL，非NULL时才进行值的必对。因此基于效率的考虑，所有字段均不能为空，即全部NOT NULL； 
     643:*预计不会存储非负数的字段，例如各项id、发帖数等，必须设置为UNSIGNED类型。UNSIGNED类型比非UNSIGNED类型所能存储的正整数范围大一倍，因此能获得更大的数值存储空间； 
     644:*存储开关、选项数据的字段，通常使用tinyint(1)非UNSIGNED类型。tinyint作为开关字段时，通常1为打开；0为关闭；-1为特殊数据，例如N/A(不可用)； 
     645:*任何类型的数据表，字段空间应当本着足够用，不浪费的原则，数值类型的字段取值范围见下表： 
     646 
     647{|border="1" cellspacing="0" 
     648|'''字段类型'''||'''存储空间(b)'''||'''UNSIGNED'''||'''取值范围''' 
     649|- 
     650|rowspan=2 |tinyint||rowspan=2 |     1||     否||     -128~127 
     651|- 
     652|是||     0~255 
     653|- 
     654|rowspan=2 |smallint||rowspan=2 |2||否||-32768~32767 
     655|- 
     656|是||0~65535 
     657|- 
     658|rowspan=2|mediumint||rowspan=2 |3||否||-8388608~8388607 
     659|- 
     660|是||0~16777215 
     661|- 
     662|rowspan=2|int||rowspan=2|4||否||-2147483648~2147483647 
     663|- 
     664|是||0~4294967295 
     665|- 
     666|rowspan=2|bigint||rowspan=2|8||否||-9223372036854775808~9223372036854775807 
     667|- 
     668|是||0~18446744073709551615 
     669|} 
     670 
     671==SQL语句== 
     672:*所有SQL语句中，除了表名、字段名称以外，全部语句和函数均需大写，应当杜绝小写方式或大小写混杂的写法。例如select * from cdb_members;是不符合规范的写法。 
     673:*很长的SQL语句应当有适当的断行，依据JOIN、FROM、ORDER BY等关键字进行界定。 
     674:*通常情况下，在对多表进行操作时，要根据不同表名称，对每个表指定一个1~2个字母的缩写，以利于语句简洁和可读性。 
     675:如下的语句范例，是符合规范的： 
     676<pre> 
     677SELECT s.*, m.* FROM sessions s, members m WHERE m.uid=s.uid AND s.sid=123456; 
     678</pre> 
     679 
     680==性能与效率== 
     681===定长与变长表=== 
     682:包含任何varchar、text等变长字段的数据表，即为变长表，反之则为定长表。 
     683:*对于变长表，由于记录大小不同，在其上进行许多删除和更改将会使表中的碎片更多。需要定期运行OPTIMIZE TABLE以保持性能。而定长表就没有这个问题； 
     684:*如果表中有可变长的字段，将它们转换为定长字段能够改进性能，因为定长记录易于处理。但在试图这样做之前，应该考虑下列问题： 
     685:*使用定长列涉及某种折衷。它们更快，但占用的空间更多。char(n) 类型列的每个值总要占用n 个字节(即使空串也是如此)，因为在表中存储时，值的长度不够将在右边补空格； 
     686:*而varchar(n)类型的列所占空间较少，因为只给它们分配存储每个值所需要的空间，每个值再加一个字节用于记录其长度。因此，如果在char和varchar类型之间进行选择，需要对时间与空间作出折衷； 
     687:*变长表到定长表的转换，不能只转换一个可变长字段，必须对它们全部进行转换。而且必须使用一个ALTER TABLE语句同时全部转换，否则转换将不起作用； 
     688:*有时不能使用定长类型，即使想这样做也不行。例如对于比255字符更长的串，没有定长类型； 
     689:*在设计表结构时如果能够使用定长数据类型尽量用定长的，因为定长表的查询、检索、更新速度都很快。必要时可以把部分关键的、承担频繁访问的表拆分，例如定长数据一个表，非定长数据一个表。例如Discuz!的cdb_members和cdb_memberfields表、cdb_forums和cdb_forumfields表等。因此规划数据结构时需要进行全局考虑； 
     690进行表结构设计时，应当做到恰到好处，反复推敲，从而实现最优的数据存储体系。 
     691===运算与检索=== 
     692:*数值运算一般比字符串运算更快。例如比较运算，可在单一运算中对数进行比较。而串运算涉及几个逐字节的比较，如果串更长的话，这种比较还要多。 
     693:*如果串列的值数目有限，应该利用普通整型或emum类型来获得数值运算的优越性。 
     694:*更小的字段类型永远比更大的字段类型处理要快得多。对于字符串，其处理时间与串长度直接相关。一般情况下，较小的表处理更快。对于定长表，应该选择最小的类型，只要能存储所需范围的值即可。例如，如果mediumint够用，就不要选择bigint。对于可变长类型，也仍然能够节省空间。一个TEXT 类型的值用2 字节记录值的长度，而一个LONGTEXT 则用4字节记录其值的长度。如果存储的值长度永远不会超过64KB，使用TEXT 将使每个值节省2字节。 
     695===结构优化与索引优化=== 
     696:索引能加快查询速度，而索引优化和查询优化是相辅相成的，既可以依据查询对索引进行优化，也可以依据现有索引对查询进行优化，这取决于修改查询或索引，哪个对现有产品架构和效率的影响最小。 
     697:索引优化与查询优化是多年经验积累的结晶，在此无法详述，但仍然给出几条最基本的准则。 
     698:首先，根据产品的实际运行和被访问情况，找出哪些SQL语句是最常被执行的。最常被执行和最常出现在程序中是完全不同的概念。最常被执行的SQL语句，又可被划分为对大表(数据条目多的)和对小表(数据条目少的)的操作。无论大表或小表，有可分为读(SELECT)多、写(UPDATE/INSERT)多或读写都多的操作。 
     699:对常被执行的SQL语句而言，对大表操作需要尤其注意： 
     700::*写操作多的，通常可使用写入缓存的方法，先将需要写或需要更新的数据缓存至文件或其他表，定期对大表进行批量写操作，例如Discuz!中点击数延迟更新机制，就是依据此原理实现。同时，应尽量使得常被读写的大表为定长类型，即便原本的结构中大表并非定长。大表定长化，可以通过改变数据存储结构和数据读取方式，将一个大表拆成一个读写多的定长表，和一个读多写少的变长表来实现； 
     701::*读操作多的，需要依据SQL查询频率设置专门针对高频SQL语句的索引和联合索引。 
     702::而小表就相对简单，加入符合查询要求的特定索引，通常效果比较明显。同时，定长化小表也有益于效率和负载能力的提高。字段比较少的小定长表，甚至可以不需要索引。 
     703:其次，看SQL语句的条件和排序字段是否动态性很高(即根据不同功能开关或属性，SQL查询条件和排序字段的变化很大的情况)，动态性过高的SQL语句是无法通过索引进行优化的。惟一的办法只有将数据缓存起来，定期更新，适用于结果对实效性要求不高的场合。 
     704::MySQL索引，常用的有PRIMARY KEY、INDEX、UNIQUE几种，详情请查阅MySQL文档。通常，在单表数据值不重复的情况下，PRIMARY KEY和UNIQUE索引比INDEX更快，请酌情使用。 
     705:事实上，索引是将条件查询、排序的读操作资源消耗，分布到了写操作中，索引越多，耗费磁盘空间越大，写操作越慢。因此，索引决不能盲目添加。对字段索引与否，最根本的出发点，依次仍然是SQL语句执行的概率、表的大小和写操作的频繁程度。 
     706 
     707===查询优化=== 
     708:MySQL中并没有提供针对查询条件的优化功能，因此需要开发者在程序中对查询条件的先后顺序人工进行优化。例如如下的SQL语句： 
     709<pre>SELECT * FROM table WHERE a>’0’ AND b<’1’ ORDER BY c LIMIT 10;</pre> 
     710:事实上无论a>’0’还是b<’1’哪个条件在前，得到的结果都是一样的，但查询速度就大不相同，尤其在对大表进行操作时。 
     711:开发者需要牢记这个原则：最先出现的条件，一定是过滤和排除掉更多结果的条件；第二出现的次之；以此类推。因而，表中不同字段的值的分布，对查询速度有着很大影响。而ORDER BY中的条件，只与索引有关，与条件顺序无关。 
     712:除了条件顺序优化以外，针对固定或相对固定的SQL查询语句，还可以通过对索引结构进行优化，进而实现相当高的查询速度。原则是：在大多数情况下，根据WHERE条件的先后顺序和ORDER BY的排序字段的先后顺序而建立的联合索引，就是与这条SQL语句匹配的最优索引结构。尽管，事实的产品中不能只考虑一条SQL语句，也不能不考虑空间占用而建立太多的索引。 
     713:同样以上面的SQL语句为例，最优的当table表的记录达到百万甚至千万级后，可以明显的看到索引优化带来的速度提升。 
     714:依据上面条件优化和索引优化的两个原则，当table表的值为如下方案时，可以得出最优的条件顺序方案： 
     715{|border="1" cellspacing="0" 
     716|字段a||字段b||字段c 
     717|- 
     718|1||7||11 
     719|- 
     720|2||8||10 
     721|- 
     722|3||9||13 
     723|- 
     724|-1||0||12 
     725|- 
     726|colspan="3"|最优条件：b<’1’ AND a>’0’ 
     727最优索引：INDEX abc (b, a, c) 
     728原因：b<’1’作为第一条件可以先过滤掉75%的结果。如果以a>’0’作为第一条件，则只能先过滤掉25%的结果<br/>'''注意：''' 
     729:*字段c由于未出现于条件中，故条件顺序优化与其无关 
     730:*最优索引由最优条件顺序得来，而非由例子中的SQL语句得来 
     731:*索引并非修改数据存储的物理顺序，而是通过对应特定偏移量的物理数据而实现的虚拟指针 
     732|} 
     733 
     734:EXPLAIN语句是检测索引和查询能否良好匹配的简便方法。在phpMyAdmin或其他MySQL客户端中运行EXPLAIN+查询语句，例如EXPLAIN SELECT * FROM table WHERE a>’0’ AND b<’1’ ORDER BY c;这种形式，即使得开发者无需模拟上百万条数据，也可以验证索引是否合理，相关细节请参考MySQL说明。 
     735:值得提出的是，Using filesort是最不应当出现的情况，如果EXPLAIN得出此结果，说明数据库为这个查询专门建立了一个用以缓存结果的临时表文件，并在查询结束后删除。众所周知，硬盘I/O速度始终是计算机存储的瓶颈，因此，查询中应当尽全力避免高执行频率的SQL语句使用filesort。尽管，开发者永远都不可能保证产品中的全部SQL语句都不会使用filesort。 
     736:限于篇幅，本文档远远没有涵盖数据库优化的方方面面，例如：联合索引与普通索引的可重用性、JOIN连接的索引设计、MEMORY/HEAP表等。数据库优化实际上就是在很多因素和利弊间不断权衡、修改，惟有在成功与失败经验中反复推敲才能得出的经验，这种经验往往就是最难能可贵和价值连城的。 
     737 
     738===兼容性问题=== 
     739:*由于MySQL 3.23至5.0的变化很大，因此程序中尽量不使用特殊的SQL语句，以免带来兼容性问题，并给数据库移植造成困难。 
     740 
     741=模板设计= 
     742==代码标记== 
     743:HTML代码标记一律采用小写字母形式，杜绝任何使用大写字母的方式 
     744 
     745==书写规则== 
     746===HTML=== 
     747:所有HTML标记参数赋值需使用双引号包含，例如，应当使用<input type=”text” name=”test” value=”ok” />,而绝对不能使用<input type=text name=test value=ok />。 
     748:在任何情况下，产品中的模板文件必须采用手写HTML代码的方式，而绝对不能使用DreamWeaver、FrontPage等自动网页制作工具进行撰写或修改。 
     749:非成对标记必须以“/>”结尾，如<br />、<input …/>,<input /> 标记的属性必须按照以下顺序书写：<input type="" name="" id="" class="" … /> 
     750=文件与目录= 
     751==文件命名== 
     752:'''普通文件''' 
     753::能够被URL直接调用的程序，例如forum.jsp、index.jsp，直接使用程序名+.jsp的方式命名 
     754:'''函数文件''' 
     755::放在jspf目录下以小写.jspf的格式命名书写。函数文件只能被其他文件引用，而不能独立运行。其中不能包含任何流程性的、不属于任何函数的程序代码。 
     756:'''流程性文件''' 
     757::此类程序用于接收输入参数和业务逻辑，放在action目录下以动词小写.jsp作为扩展名。只能被其他程序引用，而不能独立运行。 
     758:'''模板文件''' 
     759::此类程序用来显示页面，不能存放业务逻辑代码，不是可执行文件，放在templates/下的其他模板目录下，以小写.jsp作为扩展名。 
     760 
     761==目录命名== 
     762:*Discuz!目录命名以前面《命名原则》的约定为基本准则。在可能的情况下，多以复数形式出现，如./templates、./images等。 
     763:*由于目录数量较少，因此目录命名大多是一些习惯和约定俗成，开发人员如需新建目录，应与项目组成员进行磋商，达成一致后方可实施。 
     764 
     765==空目录索引== 
     766:*请在所有不包含普通程序(即能够被URL直接调用的程序)的目录中放置一个1字节的index.htm文件，内容为一个空格。几乎除应用根目录以外，所有目录都属于这一类型，因此开发者需要在这些目录全部放入空index.htm文件，以避免当http服务器的Directory Listing打开时，服务器文件被索引和列表。 
     767:*附件目录等敏感目录，要在程序中实现相应功能，当新建下级目录时，必须自动写入一个空的index.htm文件，以避免新建目录被索引的问题。 
     768