源代码编写规范(共10页)
-本页仅作为预览文档封面，使用时请删除本页-
源代码编写规范
版本<>
2
3
1 简介 ..................................................... 错误!未定义书签。
目的 .............................................. 错误!未定义书签。 范围 .............................................. 错误!未定义书签。 2 代码格式规范 ............................................. 错误!未定义书签。 3 代码注释规范 ............................................. 错误!未定义书签。 4 命名规范 ................................................. 错误!未定义书签。 5 异常处理规范 ............................................. 错误!未定义书签。 6 其他规范 ................................................. 错误!未定义书签。
4
1 简介
1.1 目的
本文用于定义本公司程序编码规范。本文的目的在于规范和指导软件编程活动，作为考核标准。 1.2 范围
本文仅用于指导软件编程工作，同时作为其他分析和设计工作的参考资料。本文的预期读者是：软件工程师/设计员、程序员。
本公司各项目可以采用不同的编程语言，并参照本规范和各语言的习惯定义各自的编程规范，但是必须经过评审通过。编程规范一旦通过评审，任何人在编程活动中都必须遵循。
2 代码格式规范
【规范1】单行代码不得超过120字符。
【规范2】每行代码最多包含一个独立的语句。 【规范3】代码缩进两个空格。
说明：两个空格已经足够清晰了，缩进量过大会导致单行代码很长，反而影响阅读。
【规范4】不要使用TAB缩进代替空格缩进。
【规范5】如果单行代码过长，则应该遵循以下规则断行：
在逗号的后面。 在操作符的前面。
断行的起始位置应该对其原行表达式的起始位置，如果无法满足，则缩进2个空格。
【规范6】每一个变量的声明独占一行。
【规范7】将变量的声明置于代码块的开始位置。
【规范8】在java中for、while、do-while循环，if、else if、else、switch-case分支，try-catch-finally块即使仅包含一个语句，也要用{}包含。其他语言参照执行。 【规范9】空行的位置：
在逻辑代码段之间。
for、while、do-while循环，if、else if、else、switch-case分支，try-catch-finally块的前面。
5
在两个类或接口的定义之间。 在两个方法/函数/过程之间。
方法/函数/过程内部变量定义行和第一个非变量定义行之间。 包含(C++)/引入(Java)完毕之后。 【规范10】空格的位置：
在一个关键字和做括号“（”之间。注意：不要在方法名和左括号之间加空格。
在参数列表的每个逗号“,”之后。
一元操作符前后。注意：二元操作符前后都不加空格。例如：int a = 10; a = a + 1; a++;
for语句的每个表达式之间。例如：for (int i = 0; i < 20; i++)… 类型转换语句之后。例如：String s = (String) c;
【建议】 空行、空格也是代码。空行是一个逻辑段起止的标志，它和编程者的思路是一致的。另外，适当的使用空行和空格可以使你的代码更加清晰。
3 代码注释规范
【规范1】代码注释的量应该不少于总代码行数的1/3。
说明：只有足够的注释才能充分的说明你的代码，没有哪个规范可以规定注释量的上限，但是一般来说1/3应该是下限。如果你的代码包括注释、空行共90行，那么注释应该不少于30行。
【规范2】在维护代码的同时，维护你的注释。
说明：我们通常在编写代码的同时都会对代码进行注释，但是往往在维护代码的时候忘记同时维护注释。所以很多注释在代码反复修改之后，失去了说明代码的作用，这样的注释还不如不写。
【规范3】注释不要重复你的代码。
例如：String str;An object of type Long
* contains a single field whose type is long. * 以上是类的作用 *
*
* In addition, this class provides several methods for converting a * long to a String and a
* String to a long, as well as other * constants and methods useful when dealing with a long. * 以上是类的使用简介 * @author Lee Boynton * @author Arthur van Hoff * 作者列表
* @version , 03/21/02
6
* 版本和时间 */
public final class Long extends Number implements Comparable { /**代码省略*/ }
摘自sun 源代码，【规范
5】为每一个方法（函数、过程）编写方法注释。
方法注释位于方法的前面,使用/**/进行注释（对于java，是/***/）。 方法的注释应该说明一下几点： 1) 该方法的作用。
2) 使用的注意事项（如果需要）。
3) 对每一个输入参数进行说明：作用，取值范围等。 4) 对返回值进行说明。
5) 对每一个抛出的异常进行说明：什么情况下出现该异常。 6) 方法注释不要写算法。 例如：
/**
* Executes the given SQL statement, which returns a single * ResultSet object. * 以上是该方法的作用
* @param sql an SQL statement to be sent to the database, typically a * static SQL SELECT statement * 以上是参数说明
* @return a ResultSet object that contains the data produced * by the given query; never null * 以上是返值说明
* @exception SQLException if a database access error occurs or the given
* SQL statement produces anything other than a single ResultSet object * 以上是异常说明 */
ResultSet executeQuery(String sql) throws SQLException; 摘自sun 源代码，【规范
6】为每一个属性编写属性注释。
属性是类的状态，应该为每一个属性编写注释：说明该属性的作用，如果需要，说明其取值范围，以及使用的注意事项。
例如：
/**
* The size of the ArrayList (the number of elements it contains). */
private int size;
摘自sun 源代码， /** The value is used for character storage. */
private char value[]; 摘自sun 源代码，【规范
7】不要编写修饰性的注释。
我们需要的是有用的代码，而不是漂亮的代码。 例如以下的注释是不被推荐的：
/***********************************************************
7
* The size of the ArrayList (the number of elements it contains).
***********************************************************/
【规范8】为每一个局部变量编写行末注释。
行末注释的好处是：具有明显的针对性。 例如： int length = 0;
【规范9】在具有复杂算法的代码块前，说明其算法。
例如：
/*
* 以下的代码采用二分法对链表进行排序，具体算法是… * */
【规范10】为每一个for、while、do-while循环，if、else if、else、switch-case分支，try-catch-finally块编写注释。
这样的地方通常体现了代码逻辑。对于复杂的代码块，可以采用/**/注释，对于简单的代码块，采用行末注释。
【规范11】对于临时代码，编写详细的注释。
临时代码就是目前不使用的，但是也许以后会用到的代码。对于这样的代码，我们通常使用/**/把它们注释起来：
1) 说明注释的原因。
2) 说明注释者，和注释时间。
3) 说明在什么情况下，可以恢复代码。
4) 说明在什么情况下，这些代码需要彻底删除。 5) 代码一旦正式发布，必须彻底删除这些注释。 例如： /*
* 有于xxx原因，将以下代码注释。 * 注释者：Sam Lee，时间 2004/03/04
* 只有xxx的情况下，才可继续使用下面的代码。 * 如果发布之前仍未使用，则删除这些代码 int a = 0;
*/
【规范12】尽量使你的注释简单。
例如：
asNext()); asNext());
【建议】在编写代码之前，编写你的注释。
编写注释有助于你仔细的思考你的代码。如果你以前没有这个习惯，请尽量养成它，你会体会到它的好处。
【规范13】对于Java、Java Script、Object ，按照JavaDoc规范编写注释。
8
请参考【规范4】、【规范5】、【规范6】，这3个规范规定的注释，形成了JavaDoc。
【规范14】对于文档注释（即【规范4】、【规范5】、【规范6】规定的注释），应该只说明“为什么这样做”，而不需要说明“怎样做”。
4 命名规范
【规范1】必须慎重的、认真的为你的每一个包、类、方法、变量命名。
说明：要起一个科学合理的名字，因为名字是理解代码的重要依据。同时，一旦代码发布，其依赖者、继承者都要永远维持这种命名。想像一下，如果你和你的同事不得不使用类似tj（统计条件）这样的名字，而又不能改变现状（会影响其他使用者），那该是一件多么痛苦的事情。 【规范2】遵循技术框架的命名规范。 【规范3】必须采用英文命名。
说明：英文是全世界软件业通用的交流语言。 【规范4】采用有意义的单词，要求望文知意。
【规范5】可以采用一个单词或多个单词或单词的缩写作为名字，缩写单词的每个字母都要大写。
【规范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 设置/获取：set/get
布耳变量的命名：isXXX，例如：isEmptySet 大小：size
工具类所在的包：util
【规范9】属性、变量、方法参数的命名规范（适用于Java、JavaScript、Object C）。
首字母小写，其他单词首字母大写。例如：userPrivilege
9
采用名词。例如：connection(而不是Connect) 关于缩写，必须符合【规范3】
【规范10】类、接口命名规范：
首字母大写，其他单词首字母大写。例如：BufferedStreamReader 采用名词。
采用单数形式，因为类或者接口代表了“一类”事物，因此通常采用单数形式。
关于缩写，必须符合【规范3】
【规范11】包的命名规范：
包名所有字母都要小写。
顶级包名采用开发者所在机构的域名的逆序。例如：、 非顶级包名采用名词，或名词的缩写。
如果不在本机构外部发布，可以直接使用项目、产品名称作为顶级包。
【规范12】方法（函数）的命名规范：
首字母小写，其他单词首字母大写（java专用）。例如：buildXML 采用强动词。例如：createJSPPage 关于缩写，必须符合【规范3】
构造方法的名字与类名相同――语法的要求。
【规范13】常量的命名规范：
常量的每一个字母大写，单词之间用下划线分隔。常量的名字必须涵盖该常量的准确意义。
例如：private static final int MAX_PATH = 255;
【规范14】数组的命名规范：
数组应该总是用下面的方式来命名： byte[] buffer; 而不是：
byte buffer[];
【规范15】存取器(accesser)方法的命名规范：
存取器方法用于获取类的一个属性或设置类的一个属性。
存取器后的单词与对应的属性名称相同，但是首字母大写（符合【规范10】）。
存取器方法的参数与对应的属性名称尽量相同。
【规范16】禁止使用“magic value”
不可为变量直接赋予非零数字或者表现为数字的字符串，请将这些数值定义为常量，大量的常量可以单独提取为常量类。不可重复的使用一个字符串，请将经常使用的字符串定义为常量。 以下是使用magic value的例子：
10
Integer lastIndex = 18; oString); } 【规范3】禁止使用FIXME注释，与其将BUG留给别人处理，不如现在就解决它。
【规范4】对于不被推荐使用的API方法，如果为了兼容性不能删除这个方法，那么请用文档注释和注解进行标注，并说明不推荐使用的原因和替换方案，以及在哪个版本中删除这个方法。 /** @deprecated Only return the length of the indent string. @see {@link #taskUnassigned} */ @Deprecated TaskQuery taskUnnassigned();
11
因篇幅问题不能全部显示，请点此查看更多更全内容