注:原文地址见: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使用了三种任务(TODO,FIXME和XXX),不要增加自定义的任务编译项,否则整个Team的人都要改变任务的编译设定。
u 按字母顺序对类中的方法排序。
u 使用有意义的数字对于数据类型的大小进行初始化,不要使用象new HashSet(65)这样的形式。
u 除非在实现类中必须使用,否则请使用接口定义变量类型以及方法签名。
u 使用存取方法(get/set)操作存取属性,不要直接操作其他类中的变量。
u 尽量早的使用if、true的方式来判断程序是否需要退出,如如果整个方法处于if(!foo){}中,那还不如用if(foo) return;
u 如对于捕获的异常不进行处理,必须说明原因(如编译警告等)。
u 如果在抛出异常时直接编写异常的信息会导致该行非常的长,Equinox Team的通常做法是首先定义好抛出异常的信息。
u 如果返回的值有可能为null,请判断。
u 使用IPath对路径进行逻辑处理,而不要使用Strings和concatenation。
u 尽量不要去捕捉Exception,而是去捕捉特定的有意义的异常。(如CoreException这些自定义的)
u 不要把整个方法都放在try{}catch(){}里面,这样会没法得到具体的错误信息。
u 确保所有的file I/O是做了缓冲处理的。
u 当代码需要与其他人共享时,确保上传到CVS的代码是可编译的。
国际化
u 按照NLS的原则以及Eclipse的NLS机制。
u 所有显示给用户的句子必须以句号结尾。
u 删除不使用的信息。