翻译的Equinox Team编码实践

注:原文地址见:http://eclipse.org/equinox/documents/coding.php

Equinox包括了相当大量的代码,Equinox团队遵循一系列的编码规范以及编码实践来保证代码的一致性。其中大部分的编码规范都可以通过Eclipse工具(Formating Setting)来实现,鉴于此,建议可以通过Eclipse的工具来保证大部分编码规范的实施。
基本原则

u       所有非提交者的贡献必须是有迹可循的。最简单的方法就是在包含了patch/贡献的Bug报告中增加[应用了贡献补丁]的注释。

u       所有的类都必须有正确的版权声明。

u       如果代码是2003年写的,那么在版权信息中不要写成2000—2003这样的形式。

代码格式标准

u       使用Equinox代码格式设定。(导入格式xml文件至eclipse)

u       设置需要导入的导入包的数字到3(之后的部分用*方式代替)

u       删除分组列表里的所有条目来屏蔽导入的分组特性。

u       在提交至CVS前格式化代码(Ctrl+Shift+F)并且组织导入的包(Ctrl+Shift+O)

u       不要滥用空行。把代码组织起来就像在写文章的时候会把句子组织成段落一样。

u       每个Equinox项目都必须使用这些设定以确保每个人的代码设定都一样。

注释

u       注释是一种好习惯。

u       API必须编写JavaDoc

u       按照Javadoc的指导编写Javadoc,就象@since作为推荐说明。

u       对于不可见的部分同样给予注释,包括方法、变量定义、算法步骤等。

命名

u       Class/method/field的命名要能代表其编写的目的。

u       在命名时注意语义上的作用。不允许以类型来命名,Java本来就是一种强类型的预言,为什么还要在命名上重复类型名呢?举例来说,setFoo(Foo value)setFoo(Foo foo)显得更为有意义。

u       尽量使用全部拼写,少用缩写。(就像getProjectValue就比getProjVal)

u       避免使用”temp””index”来对变量命名。(例外的情况同样存在,比如象在loop循环中使用i ,j 这样的短命名)

u       get/set方法应保留给真正的存取属性使用。(注:在equinox team执行时也不是完全严格的这么执行)

u       避免随机的单词前缀,如”a””the”,对于命名没有帮助。

工具的使用(Eclipse)

u       打开所有的编译提醒开关,如未使用的变量、未使用的包等等。

u       打开javadoc的编译警告。

菜单:Javadoc->Process Javadoc comments

Malformed Javadoc comments -> warning

      Report Errors in tags -> true

u       任务的编译。Equinox Team使用了三种任务(TODOFIXMEXXX),不要增加自定义的任务编译项,否则整个Team的人都要改变任务的编译设定。

u       按字母顺序对类中的方法排序。

u       使用有意义的数字对于数据类型的大小进行初始化,不要使用象new HashSet(65)这样的形式。

u       除非在实现类中必须使用,否则请使用接口定义变量类型以及方法签名。

u       使用存取方法(get/set)操作存取属性,不要直接操作其他类中的变量。

u       尽量早的使用iftrue的方式来判断程序是否需要退出,如如果整个方法处于if(!foo){}中,那还不如用if(foo) return;

u       如对于捕获的异常不进行处理,必须说明原因(如编译警告等)

u       如果在抛出异常时直接编写异常的信息会导致该行非常的长,Equinox Team的通常做法是首先定义好抛出异常的信息。

u       如果返回的值有可能为null,请判断。

u       使用IPath对路径进行逻辑处理,而不要使用Stringsconcatenation

u       尽量不要去捕捉Exception,而是去捕捉特定的有意义的异常。(CoreException这些自定义的)

u       不要把整个方法都放在try{}catch(){}里面,这样会没法得到具体的错误信息。

u       确保所有的file I/O是做了缓冲处理的。

u       当代码需要与其他人共享时,确保上传到CVS的代码是可编译的。

国际化

u       按照NLS的原则以及EclipseNLS机制。

u       所有显示给用户的句子必须以句号结尾。

u       删除不使用的信息。

posted on 2005-11-18 14:05 BlueDavy 阅读(1065) 评论(0)  编辑  收藏 所属分类: Java


只有注册用户登录后才能发表评论。


网站导航:
 

公告

 









feedsky
抓虾
google reader
鲜果

导航

<2005年11月>
303112345
6789101112
13141516171819
20212223242526
27282930123
45678910

统计

随笔分类

随笔档案

文章档案

Blogger's

搜索

最新评论

阅读排行榜

评论排行榜