`
mouer
  • 浏览: 101887 次
  • 性别: Icon_minigender_1
  • 来自: 北京
社区版块
存档分类
最新评论

Nutz Java 编码规范 (V1.0)

    博客分类:
  • J2SE
阅读更多

Nutz Java 编码规范 (V1.0)

By:zozoh<zozohtnt></zozohtnt>

0. 规范的规范

  1. 本规范的每一条目必须无二义性,并且可执行。否则作废
  2. 本规范的条目分为两个级别:
    • 规则 - R
    • 建议 - S
  3. 本规范所有的“规则”条目必须被遵守

1. 代码格式

  1. R-使用统一的 Eclipse 的代码格式: code.google.com/p/nutz/source/browse/trunk/doc/eclipse/nutz-eclipse-java-code-format-1.0.xml
    • 请从 svn 的 trunk/doc/eclipse/nutz-eclipse-java-code-format-1.0.xml 获得此文件
  2. S-非 Eclipse 用户请阅读上述 XML 代码自行遵守
    • 基本上我们没有为非 Eclipse 用户指定规范,我们还没有一个好办法

2. 命名

2.1 包

  1. R-包名必须全部小写,2个以内单词。
    1. S-最好为 1 个单数名词
    2. R-所有项目的包要以 “org.nutz” 为父 包 。

2.2 类和接口

  1. S-最好为名词
  2. R-命名类和接口时,需要将所有单词的首字母大写。
  3. R-接口的命名不采用首字母为 I 或加上 IF 后缀的命名方式 。例 如 :IBookDao 、 BookDaoIF 等 。
  4. R-抽象类必须使用 Abstract 作为类名的前缀,而接口建议使用 Interface 作为 接口名后缀。
  5. R-异常类应该使用 Exception 做为 名称 后缀。
  6. R-如果是运行一次就抛弃的类,以 ing 结尾,比如Rendering
  7. R-类名尽量短,但是最好不要缩写,如果缩写,必须为特别常用的类,比如 org.nutz.dao.Cnd
    • 因为调用者书写你的类名太长,他(她)的IDE会自动替他(她)换行,他会觉得有点不爽
  8. R-不要和 Java 的标准库中的类名冲突,比如 Class, Object, String 等
    • 如果冲突,就表示你极其藐视 Java 标准库中的那个的设计
    • 调用者需要花更多的时间和代码来明确他使用的是你的类, 而不是标准库中的那个
  9. S-以下情况可以允许写奇怪类名 -- 名称简短,让人一眼不知道什么意思,用了以后一眼就能知道什么意思
    • 类特别常用
    • 类非常特殊,难以归类
    • 私有类或内部类
    • 不推荐其他人调用的 公有、保护、默认类
      • 起个奇怪的名字,就是不想让你关心这个类的代码
  10. R-缺省接口实现应该使用 Default 名称 前缀 。例 如 : DefaultEntityMaker。
    • 也可以采用 Impl 作为后缀,表示这个实现为此接口的最优实现或者唯一实现

2.3 成员变量

  1. S-最好为单数名词
  2. R-能 private 就不要 default,能 default 就不要 protected,最好不要 public
  3. R-如果是集合或数组,用复数名词
    • Map pets, 比 Map petMap 要好
  4. R-不要用一个字母,尤其是 i,你可以用 index 或者 cursor 来代替

2.4 常量

  1. R-命名常量(带有 final 修饰符的域)时需分隔。如 : public final int MAX_VALUE = 30 。

2.5 局部变量

  1. R-局域变量名要尽量短,推荐用缩写,比如 StringBuilder sb
  2. R-总的来说局部变量请随意命名,越短越好

2.6 成员函数和静态函数

  1. R-除了 setter / getter,其他的函数采用动词或者动名短语
  2. S-以下情况可以允许写奇怪函数 -- 名称简短,让人一眼不知道什么意思,用了以后一眼就能知道什么意思
    1. 函数特别常用
    2. 函数非常特殊
    3. 私有函数或默认函数
  3. S-支持链式赋值的 setter 允许写成 ,并且也可以支持同名 getter
    // Setter
    public Pet name(String name){
    	this.name = name;
    	return this;
    }
    
    // Getter
    public String name(){
    	return this.name;
    }

3. 注释

  1. R-注释必须和代码保持同步 。
  2. R-注释中的第一个句子要以(英文)句号、问号或者感叹号结束。 Java成工具会将注释中的第一个句子放在方法汇 总表和索引中。
  3. R-如果注释中有超过一个段落,用

    标签 分隔。

  4. R-如果注释中有多个章节,用

    标签声明每个章节的标题。

  5. R-如果注释需要换行,用
    标签。
  6. R-示例代码以
     包裹。 

3.1 类 Java Doc

  1. R-要著名作者,格式为 @Author XiaoMing(xm@gmail.com)
  2. R-继承的方法可以省略注释,但是被继承方法必须有注释。

3.2 函数 Java Doc

  1. R-简单的 get/set 方法可以省略注释。
  2. R-继承的方法可以省略注释,但是被继承方法必须有注释。

3.3 字段 Java Doc

  • R-没有更多说明了

3.4 函数内部注释

  • R-行注释和块注释都是可以被接受的
  • R-不要写 JAVA 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. 编程

  1. R-你的每一次提交,必须都是编译通过的
  2. R-你的每一次提交,最好都是通过 JUnit 测试的
    • 除非有特别的情况 -- 比如你要和其他人分享的修改
  3. R-无论任何时候,同样的功能,一段更短的代码,总比更长的代码要好
    • 这里的“短”,主要指的是“逻辑”短,而不是“字符长度”短
  4. R-删掉一段代码的贡献,比增加一段代码的贡献要大,至少不比它小
  5. R-避免过度设计
    • 先让代码能工作,然后重构成为优美的代码
    • 你需要知道,“接口”固定了架构,“类” 不是,当它进化为接口的时候就固定了
    • 代码结构设计请遵循《草坪原则

5. 单元测试

  1. R-用例名请用 "长名" - 一句话,用下划线_代替空白
    • 通过这个名字,基本可以了解测试是干什么的
  2. R-主要接口和实现类要尽可能多的被用例覆盖
分享到:
评论

相关推荐

    Nutz Java 编码规范 (V1.0).doc

    【Nutz Java 编码规范 (V1.0)】...综上所述,Nutz Java编码规范强调代码的清晰性和一致性,通过命名约定、注释规范和访问控制来提升代码的可读性和维护性。开发者应当遵循这些规则,以保证代码的质量和团队协作的效率。

    java开源包4

    WARTS是一个纯Java数据库工具,可以执行字符编码识别的数据同步。开发它是用于在UTF-8 Oracle实例中使用ASCII编码的Oracle 数据库中来正确的传输非ASCII字符。 Java模板语言 Beetl Beetl,是Bee Template Language的...

    java开源包101

    WARTS是一个纯Java数据库工具,可以执行字符编码识别的数据同步。开发它是用于在UTF-8 Oracle实例中使用ASCII编码的Oracle 数据库中来正确的传输非ASCII字符。 Java模板语言 Beetl Beetl,是Bee Template Language的...

    java开源包6

    WARTS是一个纯Java数据库工具,可以执行字符编码识别的数据同步。开发它是用于在UTF-8 Oracle实例中使用ASCII编码的Oracle 数据库中来正确的传输非ASCII字符。 Java模板语言 Beetl Beetl,是Bee Template Language的...

    java开源包8

    WARTS是一个纯Java数据库工具,可以执行字符编码识别的数据同步。开发它是用于在UTF-8 Oracle实例中使用ASCII编码的Oracle 数据库中来正确的传输非ASCII字符。 Java模板语言 Beetl Beetl,是Bee Template Language的...

    java开源包9

    WARTS是一个纯Java数据库工具,可以执行字符编码识别的数据同步。开发它是用于在UTF-8 Oracle实例中使用ASCII编码的Oracle 数据库中来正确的传输非ASCII字符。 Java模板语言 Beetl Beetl,是Bee Template Language的...

    java开源包10

    WARTS是一个纯Java数据库工具,可以执行字符编码识别的数据同步。开发它是用于在UTF-8 Oracle实例中使用ASCII编码的Oracle 数据库中来正确的传输非ASCII字符。 Java模板语言 Beetl Beetl,是Bee Template Language的...

    java开源包5

    WARTS是一个纯Java数据库工具,可以执行字符编码识别的数据同步。开发它是用于在UTF-8 Oracle实例中使用ASCII编码的Oracle 数据库中来正确的传输非ASCII字符。 Java模板语言 Beetl Beetl,是Bee Template Language的...

    Java资源包01

    WARTS是一个纯Java数据库工具,可以执行字符编码识别的数据同步。开发它是用于在UTF-8 Oracle实例中使用ASCII编码的Oracle 数据库中来正确的传输非ASCII字符。 Java模板语言 Beetl Beetl,是Bee Template Language的...

    java开源包1

    WARTS是一个纯Java数据库工具,可以执行字符编码识别的数据同步。开发它是用于在UTF-8 Oracle实例中使用ASCII编码的Oracle 数据库中来正确的传输非ASCII字符。 Java模板语言 Beetl Beetl,是Bee Template Language的...

    java开源包3

    WARTS是一个纯Java数据库工具,可以执行字符编码识别的数据同步。开发它是用于在UTF-8 Oracle实例中使用ASCII编码的Oracle 数据库中来正确的传输非ASCII字符。 Java模板语言 Beetl Beetl,是Bee Template Language的...

    java开源包2

    WARTS是一个纯Java数据库工具,可以执行字符编码识别的数据同步。开发它是用于在UTF-8 Oracle实例中使用ASCII编码的Oracle 数据库中来正确的传输非ASCII字符。 Java模板语言 Beetl Beetl,是Bee Template Language的...

    java开源包11

    WARTS是一个纯Java数据库工具,可以执行字符编码识别的数据同步。开发它是用于在UTF-8 Oracle实例中使用ASCII编码的Oracle 数据库中来正确的传输非ASCII字符。 Java模板语言 Beetl Beetl,是Bee Template Language的...

    java开源包7

    WARTS是一个纯Java数据库工具,可以执行字符编码识别的数据同步。开发它是用于在UTF-8 Oracle实例中使用ASCII编码的Oracle 数据库中来正确的传输非ASCII字符。 Java模板语言 Beetl Beetl,是Bee Template Language的...

    MyEclipse代码模板

    在提供的压缩包中,`nutz-eclipse-java-code-format-1.0.xml`和`nutz-eclipse-java-codetemplates.xml`文件包含了代码格式化模板和代码模板的配置。导入这些模板的步骤如下: - 打开MyEclipse,选择`Window` -&gt; `...

Global site tag (gtag.js) - Google Analytics