Changes between Version 3 and Version 4 of standard

Timestamp:

05/02/2012 10:20:43 AM (14 years ago)

Author:

chenyang

Comment:

--

standard

@@ -37 +37 @@
  ====  类和接口声明  ==== 
 === 注释 ===
-* Java程序有两类注释：'''实现注释'''(implementation comments)和'''文档注释'''(document comments)。'''实现注释'''是那些在C++中见过的，使用/*...*/和//界定的注释。'''文档注释'''(被称为"doc comments")是Java独有的，并由/**...*/界定。文档注释可以通过javadoc工具转换成HTML文件。实现注释用以注释代码或者实现细节。文档注释从实现自由(implementation-free)的角度描述代码的规范。它可以被那些手头没有源码的开发人员读懂。
+* Java程序有两类注释：'''实现注释'''(implementation comments)和'''文档注释'''(document comments)。'''实现注释'''是那些在C++中见过的，使用/*...*/和!//界定的注释。'''文档注释'''(被称为"doc comments")是Java独有的，并由/!**...*/界定。文档注释可以通过javadoc工具转换成HTML文件。实现注释用以注释代码或者实现细节。文档注释从实现自由(implementation-free)的角度描述代码的规范。它可以被那些手头没有源码的开发人员读懂。
 * 注释应被用来给出代码的总括，并提供代码自身没有提供的附加信息。注释应该仅包含与阅读和理解程序有关的信息。例如，相应的包如何被建立或位于哪个目录下之类的信息不应包括在注释中。
 * 在注释里，对设计决策中重要的或者不是显而易见的地方进行说明是可以的，但应避免提供代码中己清晰表达出来的重复信息。多余的的注释很容易过时。通常应避免那些代码更新就可能过时的注释。
 * '''注意：频繁的注释有时反映出代码的低质量。当你觉得被迫要加注释的时候，考虑一下重写代码使其更清晰。'''
 * 注释不应写在用星号或其他字符画出来的大框里。注释不应包括诸如制表符和回退符之类的特殊字符。
-* 程序开发中难免留下一些临时代码和调试代码，此类代码必须添加注释，以免日后遗忘。所有临时性、调试性、试验性的代码，必须添加统一的注释标记“//debug”并后跟完整的注释信息，这样可以方便在程序发布和最终调试前批量检查程序中是否还存在有疑问的代码。例如：
+* 程序开发中难免留下一些临时代码和调试代码，此类代码必须添加注释，以免日后遗忘。所有临时性、调试性、试验性的代码，必须添加统一的注释标记“!//debug”并后跟完整的注释信息，这样可以方便在程序发布和最终调试前批量检查程序中是否还存在有疑问的代码。例如：
 {{{
 int num = 1;
@@ -103 +103 @@
 }}}
  ==== 文档注释 ==== 
-文档注释描述Java的类、接口、构造器，方法，以及字段(field)。每个文档注释都会被置于注释定界符/**...*/之中，一个注释对应一个类、接口或成员。该注释应位于声明之前：
+文档注释描述Java的类、接口、构造器，方法，以及字段(field)。每个文档注释都会被置于注释定界符 /!**...*/之中，一个注释对应一个类、接口或成员。该注释应位于声明之前：
 {{{
   /**
@@ -110 +110 @@
   public class Example { ...
 }}}      
-* 注意顶层的类和接口是不缩进的，而其成员是缩进的。描述类和接口的文档注释的第一行(/**)不需缩进；随后的文档注释每行都缩进1格(使星号纵向对齐)。成员，包括构造函数在内，其文档注释的第一行缩进4格，随后每行都缩进5格。
+* 注意顶层的类和接口是不缩进的，而其成员是缩进的。描述类和接口的文档注释的第一行(/!**)不需缩进；随后的文档注释每行都缩进1格(使星号纵向对齐)。成员，包括构造函数在内，其文档注释的第一行缩进4格，随后每行都缩进5格。
 * 若你想给出有关类、接口、变量或方法的信息，而这些信息又不适合写在文档中，则可使用实现块注释或紧跟在声明后面的单行注释。例如，有关一个类实现的细节，应放入紧跟在类声明后面的实现块注释中，而不是放在文档注释中。
 * 文档注释不能放在一个方法或构造器的定义块中，因为Java会将位于文档注释之后的第一个声明与其相关联。
@@ -484 +484 @@
 === 书写规则 ===
 ==== 缩进 ==== 
-'''每个缩进的单位约定是一个TAB(4个空白字符宽度)'''，需每个参与项目的开发人员在编辑器(UltraEdit、EditPlus、Vim等)中进行强制设定，以防在编写代码时遗忘而造成格式上的不规范。
+'''每个缩进的单位约定是一个TAB(4个空白字符宽度)'''，需每个参与项目的开发人员在编辑器(!UltraEdit、!EditPlus、Vim等)中进行强制设定，以防在编写代码时遗忘而造成格式上的不规范。
 本缩进规范适用于Java、JavaScript中的函数、类、逻辑结构、循环等。
 ==== 行长度 ====