源代码编写规范Word文档下载推荐.docx

1、不要在方法名和左括号之间加空格。在参数列表的每个逗号“,之后。一元操作符前后.注意：二元操作符前后都不加空格。例如：int a = 10； a = a + 1； a+;for语句的每个表达式之间。for （int i = 0; i 20； i+）类型转换语句之后.例如：String s = （String） c;【建议】 空行、空格也是代码。空行是一个逻辑段起止的标志,它和编程者的思路是一致的。另外，适当的使用空行和空格可以使你的代码更加清晰。3代码注释规范【规范1】代码注释的量应该不少于总代码行数的1/3。只有足够的注释才能充分的说明你的代码,没有哪个规范可以规定注释量的上限，但是一般来说1

2、/3应该是下限。如果你的代码包括注释、空行共90行，那么注释应该不少于30行。【规范2】在维护代码的同时，维护你的注释。我们通常在编写代码的同时都会对代码进行注释，但是往往在维护代码的时候忘记同时维护注释。所以很多注释在代码反复修改之后，失去了说明代码的作用，这样的注释还不如不写。【规范3】注释不要重复你的代码。String str;/声明一个String对象：str上面的代码看上去没有问题,但是注释却是没有用的只是对代码的简单重复。要记住,注释是用来说明代码的，而不是重复代码的。【建议】文件注释。文件注释用于说明代码文件的一些附加信息,它位于源代码文件的顶部。文件注释最重要的作用是记录代码维

3、护历史./* * 文件名:Demo。java * 作者：Sam Lee * 完成日期：2004/02/02 维护人员： 维护日期： * 维护原因:修改了对于图的深度遍历的算法 当前版本：1。 前继版本：0.9beta /【规范4】为每一个类编写类注释。类的注释位于类声明的前面，使用/进行注释（对于java，是/*/）。类的注释应该说明一下几点：1）完成了哪些工作，即这个类是作什么的.2）使用的方法和注意事项，如果比较难以表达，那么可以写一些示例代码.3）作者列表4）当前版本和完成时间5）参考类，即这个类与哪些类相关。类注释不要写类的实现方法，例如：“Matrix类采用主选消元法实现矩阵的求逆运

4、算，具体算法是：,这样的注释往往会限制类的扩展，并且加重了类的维护的工作量.我们来看一个好的类注释：/ * The Long/code class wraps a value of the primitive type * in an object。 An object of type codeLong contains a single field whose type is codelonglong and a String, as well as other constants and methods useful when dealing with a code。 以上是类的使用简介

5、author Lee Boynton * author Arthur van Hoff * 作者列表 * version 1。64， 03/21/02 版本和时间 */public final class Long extends Number implements Comparable /*代码省略/摘自sun Jdk1。4源代码，java。lang.Long【规范5】为每一个方法（函数、过程）编写方法注释。方法注释位于方法的前面，使用/*/进行注释（对于java,是/*/）.方法的注释应该说明一下几点：1）该方法的作用。2）使用的注意事项（如果需要）。3）对每一个输入参数进行说明:作用，取

6、值范围等。4）对返回值进行说明。5）对每一个抛出的异常进行说明：什么情况下出现该异常。6）方法注释不要写算法。/* * Executes the given SQL statement, which returns a single codeResultSet/code object. 以上是该方法的作用 * param sql an SQL statement to be sent to the database, typically a static SQL SELECTResultSet object that contains the data produced * by the gi

7、ven query; never codenull/code * 以上是返值说明 * exception SQLException if a database access error occurs or the given * SQL statement produces anything other than a single codeResultSet object 以上是异常说明ResultSet executeQuery（String sql） throws SQLException；摘自sun Jdk1.4源代码，java。sql。Statement【规范6】为每一个属性编写属性注

8、释。属性是类的状态，应该为每一个属性编写注释：说明该属性的作用，如果需要，说明其取值范围，以及使用的注意事项。/* The size of the ArrayList （the number of elements it contains）。private int size;uitl.ArrayList /* The value is used for character storage。private char value；lang。String【规范7】不要编写修饰性的注释。我们需要的是有用的代码，而不是漂亮的代码.例如以下的注释是不被推荐的:/* The size of the Arra

9、yList （the number of elements it contains）。*/ 【规范8】为每一个局部变量编写行末注释.行末注释的好处是：具有明显的针对性. int length = 0; /the length of the array，initial to zero。【规范9】在具有复杂算法的代码块前,说明其算法。* 以下的代码采用二分法对链表进行排序，具体算法是*/【规范10】为每一个for、while、do-while循环,if、else if、else、switch-case分支，trycatch-finally块编写注释。这样的地方通常体现了代码逻辑。对于复杂的代码块，

10、可以采用/*/注释，对于简单的代码块，采用行末注释。【规范11】对于临时代码，编写详细的注释。临时代码就是目前不使用的，但是也许以后会用到的代码.对于这样的代码,我们通常使用/把它们注释起来：1）说明注释的原因.2）说明注释者，和注释时间。3）说明在什么情况下，可以恢复代码。4）说明在什么情况下，这些代码需要彻底删除。5）代码一旦正式发布，必须彻底删除这些注释。例如:/ 有于xxx原因，将以下代码注释。 注释者:Sam Lee，时间 2004/03/04 只有xxx的情况下，才可继续使用下面的代码。 如果发布之前仍未使用，则删除这些代码 int a = 0；【规范12】尽量使你的注释简单./采

11、用Iterator遍历整个缓冲区,根据对象最后一次使用的时间，删除过期的对象while（cache.Iterator（）。hasNext（）;/删除缓冲区中过期的对象while（cache。Iterator（）.hasNext（）;【建议】在编写代码之前，编写你的注释。编写注释有助于你仔细的思考你的代码。如果你以前没有这个习惯，请尽量养成它，你会体会到它的好处。【规范13】对于Java、Java Script、Object ，按照JavaDoc规范编写注释.请参考【规范4】、【规范5】、【规范6】，这3个规范规定的注释，形成了JavaDoc。【规范14】对于文档注释（即【规范4】、【规范5】、

12、【规范6】规定的注释），应该只说明“为什么这样做”，而不需要说明“怎样做”。4命名规范【规范1】必须慎重的、认真的为你的每一个包、类、方法、变量命名。要起一个科学合理的名字，因为名字是理解代码的重要依据。同时，一旦代码发布，其依赖者、继承者都要永远维持这种命名.想像一下，如果你和你的同事不得不使用类似tj（统计？条件？）这样的名字，而又不能改变现状（会影响其他使用者）,那该是一件多么痛苦的事情。【规范2】遵循技术框架的命名规范.【规范3】必须采用英文命名.英文是全世界软件业通用的交流语言。【规范4】采用有意义的单词，要求望文知意。【规范5】可以采用一个单词或多个单词或单词的缩写作为名字，缩写单

13、词的每个字母都要大写。【规范6】对于难以使用英文的情况,可以参考相关行业标准，比如使用国标.【规范7】不要使用冠词。anUser，thePassword，someEmps，没有必要使用冠词.但是在命名的时候,要注意名词复数,例如:users、actions。【规范8】采用约定俗成的习惯用法。getUsername比receiveUsername好，虽然它们表达的意思相同。常见的习惯用法：循环变量：i、j、k、m、n临时变量：tmp、temp数据库：conn、stmt、pstmt、rs、rowSet长度：length数量：count位置：pos或position下标或索引：index设置/获取：

14、set/get布耳变量的命名:isXXX,例如：isEmptySet大小：size工具类所在的包:util【规范9】属性、变量、方法参数的命名规范（适用于Java、JavaScript、Object C）。首字母小写，其他单词首字母大写。userPrivilege采用名词。connection（而不是Connect）关于缩写，必须符合【规范3】【规范10】类、接口命名规范:首字母大写,其他单词首字母大写。BufferedStreamReader采用单数形式，因为类或者接口代表了“一类”事物,因此通常采用单数形式。【规范11】包的命名规范：包名所有字母都要小写.顶级包名采用开发者所在机构的域名的

15、逆序。org。honqun、org。jboss非顶级包名采用名词,或名词的缩写。如果不在本机构外部发布，可以直接使用项目、产品名称作为顶级包。【规范12】方法（函数）的命名规范：首字母小写，其他单词首字母大写（java专用）。buildXML采用强动词。createJSPPage构造方法的名字与类名相同语法的要求.【规范13】常量的命名规范:常量的每一个字母大写，单词之间用下划线分隔。常量的名字必须涵盖该常量的准确意义.private static final int MAX_PATH = 255;【规范14】数组的命名规范：数组应该总是用下面的方式来命名: byte buffer;而不是：b

16、yte buffer；【规范15】存取器（accesser）方法的命名规范：存取器方法用于获取类的一个属性或设置类的一个属性。存取器后的单词与对应的属性名称相同，但是首字母大写（符合【规范10】）。存取器方法的参数与对应的属性名称尽量相同。【规范16】禁止使用“magic value”不可为变量直接赋予非零数字或者表现为数字的字符串，请将这些数值定义为常量,大量的常量可以单独提取为常量类。不可重复的使用一个字符串,请将经常使用的字符串定义为常量。以下是使用magic value的例子：Integer lastIndex = 18； /错误！Integer firstIndex = 0； /0值

17、是可以使用的。String state = 1; /将1”定义为常量String name = some name”；String desc = ”some name”； /定义为常量5异常处理规范【规范1】如果需要自定义异常（Exception），那么请使用“非可检查”异常，“非可检查异常不会强制使用者处理异常，极大的简化了代码的复杂程度，提高了代码的可读性。【规范2】如果所使用的API抛出了“可检查异常，那么在处理异常的时候可以将多个不同的异常同时处理。【规范3】尽量使用系统提供的异常.如果方法参数验证失败，则抛出throw new IllegalArgumentException。【规范

18、4】处理异常,至少做以下工作：1）输出异常栈。2）用warning或者error记录日志。3）如果需要，重新抛出异常,抛出的异常必须是一个“非可检查异常。catch （Exception e） e.printStackTrace（）； logger.error（e.getMessage（）; throw new ApplicationException（e）； 【规范5】不要用异常代替逻辑。“异常”代表了不可预测的情况，而逻辑一定是可以预测的，因此，不要用异常代替逻辑。简单的说，在catch代码中只能有处理异常的代码，不能加入逻辑代码。6其他规范【规范1】禁止拷贝粘贴代码.当你 CopyPas

19、te 代码的时候，说明代码中存在重复，重复的代码往往导致代码难以维护和阅读。一旦那些保存在剪切板中的代码中存在错误，编写者甚至不知道到哪里修改这些错误。每当你 Copy-Paste 代码的时候，请停下来，考虑将这些代码提取为方法、类或者组件。【规范2】对于暂时无法实现的代码，使用/ TODO ：进行注释。下面的代码，用于处理日期类型,但是,在可以预期的需求中,还要处理时间类型：if （StringUtils。equalsIgnoreCase（field.getDataType（）， AnyDataModelConstants。DATA_TYPE_DATE） / TODO:转换日期类型（目前不支

20、持时间类型） row。put（key, new DateTime（Date） value）.toString（Constants.DATE_PATTERN）； 【规范3】禁止使用FIXME注释，与其将BUG留给别人处理，不如现在就解决它。【规范4】对于不被推荐使用的API方法，如果为了兼容性不能删除这个方法，那么请用文档注释和注解进行标注，并说明不推荐使用的原因和替换方案，以及在哪个版本中删除这个方法。/*deprecated Only return the length of the indent string。see link taskUnassigned */ Deprecated TaskQuery taskUnnassigned（）;