Nutz Java 编码规范 (V1.0)
2012-11-23 09:38
357 查看
Nutz Java 编码规范 (V1.0)
10. 规范的规范
21. 代码格式
32. 命名
3.12.1 包
3.22.2 类和接口
3.32.3 成员变量
3.42.4 常量
3.52.5 局部变量
3.62.6 成员函数和静态函数
43. 注释
4.13.1 类 Java Doc
4.23.2 函数 Java Doc
4.33.3 字段 Java Doc
4.43.4 函数内部注释
54. 编程
65. 单元测试
本规范的每一条目必须无二义性,并且可执行。否则作废
本规范的条目分为两个级别:
规则 - R
建议 - S
本规范所有的“规则”条目必须被遵守
R-使用统一的 Eclipse 的代码格式: https://github.com/nutzam/nutz/blob/master/doc/eclipse/nutz-eclipse-java-code-format-1.0.xml
请从 github项目中 获得此文件
S-非 Eclipse 用户请阅读上述 XML 代码自行遵守
基本上我们没有为非 Eclipse 用户指定规范,我们还没有一个好办法
Top
R-包名必须全部小写,2个以内单词。
S-最好为 1 个单数名词
R-所有项目的包要以 “org.nutz” 为父 包 。
Top
S-最好为名词
R-命名类和接口时,需要将所有单词的首字母大写。
R-接口的命名不采用首字母为 I 或加上 IF 后缀的命名方式 。例 如 :IBookDao 、 BookDaoIF 等 。
R-抽象类必须使用 Abstract 作为类名的前缀,而接口建议使用 Interface 作为 接口名后缀。
R-异常类应该使用 Exception 做为 名称 后缀。
R-如果是运行一次就抛弃的类,以 ing 结尾,比如Rendering
R-类名尽量短,但是最好不要缩写,如果缩写,必须为特别常用的类,比如 org.nutz.dao.Cnd
因为调用者书写你的类名太长,他(她)的IDE会自动替他(她)换行,他会觉得有点不爽
R-不要和 Java 的标准库中的类名冲突,比如 Class, Object, String 等
如果冲突,就表示你极其藐视 Java 标准库中的那个的设计
调用者需要花更多的时间和代码来明确他使用的是你的类, 而不是标准库中的那个
S-以下情况可以允许写奇怪类名 -- 名称简短,让人一眼不知道什么意思,用了以后一眼就能知道什么意思
类特别常用
类非常特殊,难以归类
私有类或内部类
不推荐其他人调用的 公有、保护、默认类
起个奇怪的名字,就是不想让你关心这个类的代码
R-缺省接口实现应该使用 Default 名称 前缀 。例 如 : DefaultEntityMaker。
也可以采用 Impl 作为后缀,表示这个实现为此接口的最优实现或者唯一实现
Top
S-最好为单数名词
R-能 private 就不要 default,能 default 就不要 protected,最好不要 public
R-如果是集合或数组,用复数名词
Map pets, 比 Map petMap 要好
R-不要用一个字母,尤其是 i,你可以用 index 或者 cursor 来代替
Top
R-命名常量(带有 final 修饰符的域)时需分隔。如 : public final int MAX_VALUE = 30 。
Top
R-局域变量名要尽量短,推荐用缩写,比如 StringBuilder sb
R-总的来说局部变量请随意命名,越短越好
比如这个就不好
而这个就很容易阅读了:
Top
R-除了 setter / getter,其他的函数采用动词或者动名短语
S-以下情况可以允许写奇怪函数 -- 名称简短,让人一眼不知道什么意思,用了以后一眼就能知道什么意思
函数特别常用
函数非常特殊
私有函数或默认函数
S-支持链式赋值的 setter 允许写成 ,并且也可以支持同名 getter
R-注释必须和代码保持同步 。
R-注释中的第一个句子要以(英文)句号、问号或者感叹号结束。 Java成工具会将注释中的第一个句子放在方法汇总表和索引中。
R-如果注释中有超过一个段落,用 <P> 标签 分隔。
R-如果注释中有多个章节,用 <H2> 标签声明每个章节的标题。
R-如果注释需要换行,用 <BR> 标签。
R-示例代码以 <PRE></PRE> 包裹。
Top
R-要著名作者,格式为 @Author XiaoMing(xm@gmail.com)
R-继承的方法可以省略注释,但是被继承方法必须有注释。
Top
R-简单的 get/set 方法可以省略注释。
R-继承的方法可以省略注释,但是被继承方法必须有注释。
Top
R-没有更多说明了
Top
R-行注释和块注释都是可以被接受的
R-不要写 J***A DOC,没意义
R-代码质量不好但能正常运行,或者还没有实现的代码用 “ //TODO: ”
R-在 if ... else .. 分支上做注释格式应该如下:
R-你的每一次提交,必须都是编译通过的
R-你的每一次提交,最好都是通过 JUnit 测试的
除非有特别的情况 -- 比如你要和其他人分享的修改
R-无论任何时候,同样的功能,一段更短的代码,总比更长的代码要好
这里的“短”,主要指的是“逻辑”短,而不是“字符长度”短
R-删掉一段代码的贡献,比增加一段代码的贡献要大,至少不比它小
R-避免过度设计
先让代码能工作,然后重构成为优美的代码
你需要知道,“接口”固定了架构,“类” 不是,当它进化为接口的时候就固定了
代码结构设计请遵循《草坪原则》
R-用例名请用 "长名" - 一句话,用下划线_代替空白
通过这个名字,基本可以了解测试是干什么的
R-主要接口和实现类要尽可能多的被用例覆盖
10. 规范的规范
21. 代码格式
32. 命名
3.12.1 包
3.22.2 类和接口
3.32.3 成员变量
3.42.4 常量
3.52.5 局部变量
3.62.6 成员函数和静态函数
43. 注释
4.13.1 类 Java Doc
4.23.2 函数 Java Doc
4.33.3 字段 Java Doc
4.43.4 函数内部注释
54. 编程
65. 单元测试
0. 规范的规范
Top本规范的每一条目必须无二义性,并且可执行。否则作废
本规范的条目分为两个级别:
规则 - R
建议 - S
本规范所有的“规则”条目必须被遵守
1. 代码格式
TopR-使用统一的 Eclipse 的代码格式: https://github.com/nutzam/nutz/blob/master/doc/eclipse/nutz-eclipse-java-code-format-1.0.xml
请从 github项目中 获得此文件
S-非 Eclipse 用户请阅读上述 XML 代码自行遵守
基本上我们没有为非 Eclipse 用户指定规范,我们还没有一个好办法
2. 命名
Top
2.1 包
TopR-包名必须全部小写,2个以内单词。
S-最好为 1 个单数名词
R-所有项目的包要以 “org.nutz” 为父 包 。
2.2 类和接口
TopS-最好为名词
R-命名类和接口时,需要将所有单词的首字母大写。
R-接口的命名不采用首字母为 I 或加上 IF 后缀的命名方式 。例 如 :IBookDao 、 BookDaoIF 等 。
R-抽象类必须使用 Abstract 作为类名的前缀,而接口建议使用 Interface 作为 接口名后缀。
R-异常类应该使用 Exception 做为 名称 后缀。
R-如果是运行一次就抛弃的类,以 ing 结尾,比如Rendering
R-类名尽量短,但是最好不要缩写,如果缩写,必须为特别常用的类,比如 org.nutz.dao.Cnd
因为调用者书写你的类名太长,他(她)的IDE会自动替他(她)换行,他会觉得有点不爽
R-不要和 Java 的标准库中的类名冲突,比如 Class, Object, String 等
如果冲突,就表示你极其藐视 Java 标准库中的那个的设计
调用者需要花更多的时间和代码来明确他使用的是你的类, 而不是标准库中的那个
S-以下情况可以允许写奇怪类名 -- 名称简短,让人一眼不知道什么意思,用了以后一眼就能知道什么意思
类特别常用
类非常特殊,难以归类
私有类或内部类
不推荐其他人调用的 公有、保护、默认类
起个奇怪的名字,就是不想让你关心这个类的代码
R-缺省接口实现应该使用 Default 名称 前缀 。例 如 : DefaultEntityMaker。
也可以采用 Impl 作为后缀,表示这个实现为此接口的最优实现或者唯一实现
2.3 成员变量
TopS-最好为单数名词
R-能 private 就不要 default,能 default 就不要 protected,最好不要 public
R-如果是集合或数组,用复数名词
Map pets, 比 Map petMap 要好
R-不要用一个字母,尤其是 i,你可以用 index 或者 cursor 来代替
2.4 常量
TopR-命名常量(带有 final 修饰符的域)时需分隔。如 : public final int MAX_VALUE = 30 。
2.5 局部变量
TopR-局域变量名要尽量短,推荐用缩写,比如 StringBuilder sb
R-总的来说局部变量请随意命名,越短越好
比如这个就不好
public String abc(String str){ AbcObjectSet abcObjectSet = new AbcObjectSet(); abcObjectSet.setName(str); return abcObjectSet.getBrief(); }
而这个就很容易阅读了:
public String abc(String str){ AbcObjectSet aos = new AbcObjectSet(); aos.setName(str); return aos.getBrief(); }
2.6 成员函数和静态函数
TopR-除了 setter / getter,其他的函数采用动词或者动名短语
S-以下情况可以允许写奇怪函数 -- 名称简短,让人一眼不知道什么意思,用了以后一眼就能知道什么意思
函数特别常用
函数非常特殊
私有函数或默认函数
S-支持链式赋值的 setter 允许写成 ,并且也可以支持同名 getter
// Setter public Pet name(String name){ this.name = name; return this; } // Getter public String name(){ return this.name; }
3. 注释
TopR-注释必须和代码保持同步 。
R-注释中的第一个句子要以(英文)句号、问号或者感叹号结束。 Java成工具会将注释中的第一个句子放在方法汇总表和索引中。
R-如果注释中有超过一个段落,用 <P> 标签 分隔。
R-如果注释中有多个章节,用 <H2> 标签声明每个章节的标题。
R-如果注释需要换行,用 <BR> 标签。
R-示例代码以 <PRE></PRE> 包裹。
3.1 类 Java Doc
TopR-要著名作者,格式为 @Author XiaoMing(xm@gmail.com)
R-继承的方法可以省略注释,但是被继承方法必须有注释。
3.2 函数 Java Doc
TopR-简单的 get/set 方法可以省略注释。
R-继承的方法可以省略注释,但是被继承方法必须有注释。
3.3 字段 Java Doc
TopR-没有更多说明了
3.4 函数内部注释
TopR-行注释和块注释都是可以被接受的
R-不要写 J***A DOC,没意义
R-代码质量不好但能正常运行,或者还没有实现的代码用 “ //TODO: ”
R-在 if ... else .. 分支上做注释格式应该如下:
// comments for case A if(xxxx){ //TODO you code here } /* * Multipline comments for case B */ else if(xxxxx){ //TODO you code here } // comments for default case else{ //TODO you code here }
4. 编程
TopR-你的每一次提交,必须都是编译通过的
R-你的每一次提交,最好都是通过 JUnit 测试的
除非有特别的情况 -- 比如你要和其他人分享的修改
R-无论任何时候,同样的功能,一段更短的代码,总比更长的代码要好
这里的“短”,主要指的是“逻辑”短,而不是“字符长度”短
R-删掉一段代码的贡献,比增加一段代码的贡献要大,至少不比它小
R-避免过度设计
先让代码能工作,然后重构成为优美的代码
你需要知道,“接口”固定了架构,“类” 不是,当它进化为接口的时候就固定了
代码结构设计请遵循《草坪原则》
5. 单元测试
TopR-用例名请用 "长名" - 一句话,用下划线_代替空白
通过这个名字,基本可以了解测试是干什么的
R-主要接口和实现类要尽可能多的被用例覆盖
相关文章推荐
- Java编码规范,让你的代码赏心悦目--有意义的命名
- Java编码规范,让你的代码赏心悦目--函数
- Java编码规范,让你的代码赏心悦目--格式
- [原]关于java的编码规范的一些想法
- Eclipse_Java编码规范详细设置
- [Coding Style]官方Java编码规范
- 开发java编码命名规范
- JAVA程序员不可不注意的编码规范
- Java/Android 编码规范,从第一行代码开始
- JAVA编码规范[转贴]
- Java语言的编码规范
- 【Java编码规范】《阿里巴巴Java开发手册(正式版)》【转载】
- (续)JAVA应用技术之编码规范(Eclipse checkstyle plugin)
- java性能编码规范整理一
- [收藏]Java编码规范
- 官方Java编码规范
- Java编码规范整理
- Java 程序编码规范
- Java编码规范,让你的代码赏心悦目--错误处理
- Java程序的编码规范