源代码编写规范Word文档下载推荐.docx
《源代码编写规范Word文档下载推荐.docx》由会员分享,可在线阅读,更多相关《源代码编写规范Word文档下载推荐.docx(11页珍藏版)》请在冰豆网上搜索。
![源代码编写规范Word文档下载推荐.docx](https://file1.bdocx.com/fileroot1/2023-1/9/3ef52627-04e5-4b8d-99d2-2c9d5eefd78f/3ef52627-04e5-4b8d-99d2-2c9d5eefd78f1.gif)
不要在方法名和左括号之间加空格。
♦在参数列表的每个逗号“,"
之后。
♦一元操作符前后.注意:
二元操作符前后都不加空格。
例如:
inta=10;
a=a+1;
a++;
♦for语句的每个表达式之间。
for(inti=0;
i〈20;
i++)…
♦类型转换语句之后.例如:
Strings=(String)c;
【建议】空行、空格也是代码。
空行是一个逻辑段起止的标志,它和编程者的思路是一致的。
另外,适当的使用空行和空格可以使你的代码更加清晰。
3代码注释规范
【规范1】代码注释的量应该不少于总代码行数的1/3。
只有足够的注释才能充分的说明你的代码,没有哪个规范可以规定注释量的上限,但是一般来说1/3应该是下限。
如果你的代码包括注释、空行共90行,那么注释应该不少于30行。
【规范2】在维护代码的同时,维护你的注释。
我们通常在编写代码的同时都会对代码进行注释,但是往往在维护代码的时候忘记同时维护注释。
所以很多注释在代码反复修改之后,失去了说明代码的作用,这样的注释还不如不写。
【规范3】注释不要重复你的代码。
Stringstr;
//声明一个String对象:
str
上面的代码看上去没有问题,但是注释却是没有用的――只是对代码的简单重复。
要记住,注释是用来说明代码的,而不是重复代码的。
【建议】文件注释。
文件注释用于说明代码文件的一些附加信息,它位于源代码文件的顶部。
文件注释最重要的作用是记录代码维护历史.
/*
*文件名:
Demo。
java
*作者:
SamLee
*完成日期:
2004/02/02
*维护人员:
*维护日期:
*维护原因:
修改了对于图的深度遍历的算法
*当前版本:
1。
*前继版本:
0.9beta
*/
【规范4】为每一个类编写类注释。
类的注释位于类声明的前面,使用/**/进行注释(对于java,是/***/)。
类的注释应该说明一下几点:
1)完成了哪些工作,即这个类是作什么的.
2)使用的方法和注意事项,如果比较难以表达,那么可以写一些示例代码.
3)作者列表
4)当前版本和完成时间
5)参考类,即这个类与哪些类相关。
类注释不要写类的实现方法,例如:
“Matrix类采用主选消元法实现矩阵的求逆运算,具体算法是:
…"
这样的注释往往会限制类的扩展,并且加重了类的维护的工作量.
我们来看一个好的类注释:
/**
*The<
code>
Long<
/code〉classwrapsavalueoftheprimitivetype
*<
long〈/code>
inanobject。
Anobjectoftype〈code〉Long<
/code>
*containsasinglefieldwhosetypeis〈code〉long<
/code〉.
*以上是类的作用
*〈p〉
*
*Inaddition,thisclassprovidesseveralmethodsforconvertinga
*〈code>
long<
toa〈code〉String〈/code>
anda
*<
String<
toa〈code>
aswellasother
*constantsandmethodsusefulwhendealingwitha〈code>
。
*以上是类的使用简介
*@authorLeeBoynton
*@authorArthurvanHoff
*作者列表
*@version1。
64,03/21/02
*版本和时间
*/
publicfinalclassLongextendsNumberimplementsComparable{
/**代码省略*/
}
摘自sunJdk1。
4源代码,java。
lang.Long
【规范5】为每一个方法(函数、过程)编写方法注释。
方法注释位于方法的前面,使用/**/进行注释(对于java,是/***/).
方法的注释应该说明一下几点:
1)该方法的作用。
2)使用的注意事项(如果需要)。
3)对每一个输入参数进行说明:
作用,取值范围等。
4)对返回值进行说明。
5)对每一个抛出的异常进行说明:
什么情况下出现该异常。
6)方法注释不要写算法。
/**
*ExecutesthegivenSQLstatement,whichreturnsasingle
*〈code〉ResultSet〈/code>
object.
*以上是该方法的作用
*@paramsqlanSQLstatementtobesenttothedatabase,typicallya
*staticSQL<
SELECT<
/code〉statement
*以上是参数说明
*@returna〈code>
ResultSet<
objectthatcontainsthedataproduced
*bythegivenquery;
never<
code〉null<
/code〉
*以上是返值说明
*@exceptionSQLExceptionifadatabaseaccesserroroccursorthegiven
*SQLstatementproducesanythingotherthanasingle<
code〉ResultSet<
object
*以上是异常说明
ResultSetexecuteQuery(Stringsql)throwsSQLException;
摘自sunJdk1.4源代码,java。
sql。
Statement
【规范6】为每一个属性编写属性注释。
属性是类的状态,应该为每一个属性编写注释:
说明该属性的作用,如果需要,说明其取值范围,以及使用的注意事项。
/**
*ThesizeoftheArrayList(thenumberofelementsitcontains)。
privateintsize;
uitl.ArrayList
/**Thevalueisusedforcharacterstorage。
privatecharvalue[];
lang。
String
【规范7】不要编写修饰性的注释。
我们需要的是有用的代码,而不是漂亮的代码.
例如以下的注释是不被推荐的:
/***********************************************************
*ThesizeoftheArrayList(thenumberofelementsitcontains)。
***********************************************************/
【规范8】为每一个局部变量编写行末注释.
行末注释的好处是:
具有明显的针对性.
intlength=0;
//thelengthofthearray,initialtozero。
【规范9】在具有复杂算法的代码块前,说明其算法。
*以下的代码采用二分法对链表进行排序,具体算法是…
*
*/
【规范10】为每一个for、while、do-while循环,if、elseif、else、switch-case分支,try—catch-finally块编写注释。
这样的地方通常体现了代码逻辑。
对于复杂的代码块,可以采用/**/注释,对于简单的代码块,采用行末注释。
【规范11】对于临时代码,编写详细的注释。
临时代码就是目前不使用的,但是也许以后会用到的代码.对于这样的代码,我们通常使用/**/把它们注释起来:
1)说明注释的原因.
2)说明注释者,和注释时间。
3)说明在什么情况下,可以恢复代码。
4)说明在什么情况下,这些代码需要彻底删除。
5)代码一旦正式发布,必须彻底删除这些注释。
例如:
/*
*有于xxx原因,将以下代码注释。
*注释者:
SamLee,时间2004/03/04
*只有xxx的情况下,才可继续使用下面的代码。
*如果发布之前仍未使用,则删除这些代码
inta=0;
【规范12】尽量使你的注释简单.
//采用Iterator遍历整个缓冲区,根据对象最后一次使用的时间,删除过期的对象
while(cache.Iterator()。
hasNext());
//删除缓冲区中过期的对象
while(cache。
Iterator().hasNext());
【建议】在编写代码之前,编写你的注释。
编写注释有助于你仔细的思考你的代码。
如果你以前没有这个习惯,请尽量养成它,你会体会到它的好处。
【规范13】对于Java、JavaScript、Object,按照JavaDoc规范编写注释.
请参考【规范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、ObjectC)。
♦首字母小写,其他单词首字母大写。
userPrivilege
♦采用名词。
connection(而不是Connect)
♦关于缩写,必须符合【规范3】
【规范10】类、接口命名规范:
♦首字母大写,其他单词首字母大写。
BufferedStreamReader
♦采用单数形式,因为类或者接口代表了“一类”事物,因此通常采用单数形式。
【规范11】包的命名规范:
♦包名所有字母都要小写.
♦顶级包名采用开发者所在机构的域名的逆序。
org。
honqun、org。
jboss
♦非顶级包名采用名词,或名词的缩写。
♦如果不在本机构外部发布,可以直接使用项目、产品名称作为顶级包。
【规范12】方法(函数)的命名规范:
♦首字母小写,其他单词首字母大写(java专用)。
buildXML
♦采用强动词。
createJSPPage
♦构造方法的名字与类名相同――语法的要求.
【规范13】常量的命名规范:
常量的每一个字母大写,单词之间用下划线分隔。
常量的名字必须涵盖该常量的准确意义.
privatestaticfinalintMAX_PATH=255;
【规范14】数组的命名规范:
数组应该总是用下面的方式来命名:
byte[]buffer;
而不是:
bytebuffer[];
【规范15】存取器(accesser)方法的命名规范:
♦存取器方法用于获取类的一个属性或设置类的一个属性。
♦存取器后的单词与对应的属性名称相同,但是首字母大写(符合【规范10】)。
存取器方法的参数与对应的属性名称尽量相同。
【规范16】禁止使用“magicvalue”
不可为变量直接赋予非零数字或者表现为数字的字符串,请将这些数值定义为常量,大量的常量可以单独提取为常量类。
不可重复的使用一个字符串,请将经常使用的字符串定义为常量。
以下是使用magicvalue的例子:
IntegerlastIndex=18;
//错误!
IntegerfirstIndex=0;
//0值是可以使用的。
Stringstate="
1"
;
//将"
1”定义为常量
Stringname="
somename”;
Stringdesc=”somename”;
//定义为常量
5异常处理规范
【规范1】如果需要自定义异常(Exception),那么请使用“非可检查”异常,“非可检查"
异常不会强制使用者处理异常,极大的简化了代码的复杂程度,提高了代码的可读性。
【规范2】如果所使用的API抛出了“可检查"
异常,那么在处理异常的时候可以将多个不同的异常同时处理。
【规范3】尽量使用系统提供的异常.
如果方法参数验证失败,则抛出thrownewIllegalArgumentException。
【规范4】处理异常,至少做以下工作:
1)输出异常栈。
2)用warning或者error记录日志。
3)如果需要,重新抛出异常,抛出的异常必须是一个“非可检查"
异常。
catch(Exceptione){
e.printStackTrace();
logger.error(e.getMessage());
thrownewApplicationException(e);
}
【规范5】不要用异常代替逻辑。
“异常”代表了不可预测的情况,而逻辑一定是可以预测的,因此,不要用异常代替逻辑。
简单的说,在catch代码中只能有处理异常的代码,不能加入逻辑代码。
6其他规范
【规范1】禁止拷贝粘贴代码.当你Copy—Paste代码的时候,说明代码中存在重复,重复的代码往往导致代码难以维护和阅读。
一旦那些保存在剪切板中的代码中存在错误,编写者甚至不知道到哪里修改这些错误。
每当你Copy-Paste代码的时候,请停下来,考虑将这些代码提取为方法、类或者组件。
【规范2】对于暂时无法实现的代码,使用//TODO:
进行注释。
下面的代码,用于处理日期类型,但是,在可以预期的需求中,还要处理时间类型:
if(StringUtils。
equalsIgnoreCase(field.getDataType(),AnyDataModelConstants。
DATA_TYPE_DATE)){//TODO:
转换日期类型(目前不支持时间类型)
row。
put(key,newDateTime((Date)value).toString(Constants.DATE_PATTERN));
}
【规范3】禁止使用FIXME注释,与其将BUG留给别人处理,不如现在就解决它。
【规范4】对于不被推荐使用的API方法,如果为了兼容性不能删除这个方法,那么请用文档注释和注解进行标注,并说明不推荐使用的原因和替换方案,以及在哪个版本中删除这个方法。
/**
@deprecatedOnlyreturnthelengthoftheindentstring。
@see{@link#taskUnassigned}*/
@Deprecated
TaskQuerytaskUnnassigned();