编码规范(一)----JAVA注释规范

浅浅的花香味﹌ 2022-06-03 03:47 488阅读 0赞

**一、前言**

好的代码规范是一个程序员的基本修炼，好的代码注释更能体现一个程序员的思维逻辑，虽然代码是用来给机器运行的，我们只要能写出能让编译器运行的代码就行了，但是如果没有好的编码规范，到项目后期，加入开发的人员逐渐增多时，每个人的编码风格都不一样，这就会让项目维护者很难维护，所以开始就要制定一些好的规范来让大家遵守，这样才能写出可维护，健壮的项目，这就是接下来要做的事情。第一节从要从代码注释这一块说起，包含: 版权注释、类注释(Class)、构造函数注释(Constructor)、方法注释(Methods)、代码块注释(Block)、单句注释、字段名注释，然后分别为eclipse、IDEA创建注释模块等。

**二、约定**

下面就是一些常见的注释示例:

**1、版权注释**

版权注释主要用来声明公司的一些基本信息等:

/** 
     * projectName: xxx
     * fileName: Tk.java 
     * packageName: xxxx
     * date: 2017年12月18日下午12:28:39 
     * copyright(c) 2017-2020 xxx公司
     */

**2、类注释(Class)**

类注释(Class)主要用来声明该类用来做什么，以及创建者、创建日期版本、包名等一些信息:

/**
     * @version: V1.0
     * @author: fendo
     * @className: user
     * @packageName: user
     * @description: 这是用户类
     * @data: 2017-07-28 12:20
     **/

**3、构造函数注释(Constructor)**

构造函数注释(Constructor)主要用来声明该类的构造函数、入参等信息:

**
    * @description: 构造函数
    * @param: [sid, pid]
    */

**4、方法注释(Methods)**

方法注释(Methods)主要用来声明该类的作用、入参、返回值、异常等信息:

/**
    * @author:  fendo
    * @methodsName: addUser
    * @description: 添加一个用户
    * @param:  xxxx
    * @return: String
    * @throws: 
    */

**5、代码块注释(Block)**

/**
     * 实例化一个用户
     * xxxxxxx
     */
    User user=new User();

**6、单句注释**

User user=new User();  //实例化一个用户

**7、字段名注释**

/**
     * 用户名
     */
    public String name;

或者使用如下格式:

/**用户名**/
    public String name;

**三、IDE模板**

接下来就是分别在Eclipse和IDEA中实现上面的注释，然后分别生成模板:

**3.1、Eclipse代码注释**

在Eclipse中可以通过CodeTemplates进行设置，具体步骤如下: Window->Preference->Java->Code Style->Code Template

![20171217212328913][]

其中有两类一类是Comments、主要是类中的一些通用模板:

![20171217205751012][]

**1.文件(Files)注释标签：**

设置版权信息:

/** 
     * projectName: ${project_name} 
     * fileName: ${file_name} 
     * packageName: ${package_name} 
     * date: ${date}${time} 
     * copyright(c) 2017-2020 xxx公司
     */

![20171217212638811][]

注意: 要打上勾!!

**2.类型(Types)注释标签(类的注释)：**

/**   
     * @title: ${file_name} 
     * @package ${package_name} 
     * @description: ${todo}
     * @author: fendo
     * @date: ${date} ${time} 
     * @version: V1.0   
    */

![20171217211025679][]

**3.字段(Fields)注释标签：**

/**   
     * @Fields ${field} : ${todo}(用一句话描述这个变量表示什么)   
     */

**4.构造函数(Constructors)标签：**

/**   
     * @title: ${enclosing_type}   
     * @description: ${todo}(这里用一句话描述这个方法的作用)   
     * @param: ${tags}  
     * @throws:   
     */

**5.方法(Methods)标签：**

/**
     *@title: ${enclosing_method} 
     *@description: ${todo}
     *@author: fendo
     *@date: ${date} ${time}
     *${tags}
     *@throws: 
     */

6.覆盖方法(Overriding Methods)标签:

/**   
     * @title: ${enclosing_method}
     * @description: ${todo}
     * ${tags}   
     * ${see_to_overridden}     
     */

**7.代表方法(Delegate Methods)标签：**

/**  
     * ${tags}  
     * ${see_to_target}  
     */

**8.Getter方法标签：**

/**  
     * @title: ${enclosing_method}
     * @description: ${todo}
     * @return: ${field_type}
     */

**9.Setter方法标签：**

/**  
     * @title: ${enclosing_method}
     * @description: ${todo}
     * @return: ${field_type}
     */

另一类是代码模板如下:

![20171217205841671][]

由于基本的在上面的已经设置好了，所以这里也不需要设置什么，然后就是把这个模板导出来，分发给各开发人员，让他们导进来就行了。

![20171217212959927][]

完整的模板如下:

<?xml version="1.0" encoding="UTF-8" standalone="no"?><templates><template autoinsert="false" context="gettercomment_context" deleted="false" description="Comment for getter method" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.gettercomment" name="gettercomment">/**  
     * @title: ${enclosing_method}
     * @description: ${todo}
     * @return: ${field_type}
     */  </template><template autoinsert="false" context="constructorcomment_context" deleted="false" description="Comment for created constructors" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.constructorcomment" name="constructorcomment">/**   
     * @title: ${enclosing_type}   
     * @description: ${todo}
     * @param: ${tags}  
     * @throws   
     */ </template><template autoinsert="false" context="filecomment_context" deleted="false" description="Comment for created Java files" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.filecomment" name="filecomment">/** 
     * projectName:${project_name} 
     * fileName:${file_name} 
     * packageName:${package_name} 
     * date:${date}${time} 
     * copyright(c) 2017-2020 xxx公司
     */</template><template autoinsert="false" context="typecomment_context" deleted="false" description="Comment for created types" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.typecomment" name="typecomment">/**   
     * @title: ${file_name} 
     * @package ${package_name} 
     * @description: ${todo}
     * @author: fendo
     * @date: ${date} ${time} 
     * @version: V1.0   
    */</template><template autoinsert="false" context="methodcomment_context" deleted="false" description="Comment for non-overriding methods" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.methodcomment" name="methodcomment">/**
     *@title ${enclosing_method} 
     *@description: ${todo}
     *@author: fendo
     *@date: ${date} ${time}
     *${tags}
     *@throws 
     */ </template><template autoinsert="false" context="overridecomment_context" deleted="false" description="Comment for overriding methods" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.overridecomment" name="overridecomment">/**   
     * @title: ${enclosing_method}
     * @description: ${todo}
     * ${tags}   
     * ${see_to_overridden}     
     */ </template><template autoinsert="false" context="settercomment_context" deleted="false" description="Comment for setter method" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.settercomment" name="settercomment">/**  
     * @title: ${enclosing_method}
     * @description: ${todo}
     * @return: ${field_type}
     */</template><template autoinsert="false" context="fieldcomment_context" deleted="false" description="Comment for fields" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.fieldcomment" name="fieldcomment">/**   
     * @Fields ${field} : ${todo}
     */  </template><template autoinsert="false" context="delegatecomment_context" deleted="false" description="Comment for delegate methods" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.delegatecomment" name="delegatecomment">/**  
     * ${tags}  
     * ${see_to_target}  
     */  </template></templates>

**3.2、IDEA代码注释**

idea有两种快捷方式，一个是live templates，一个是file and code templates。

**3.2.1、file and code templates**

IDEA的code templates仅限于类文件头和所有文件头。配置如下图：

File -- Settings -- Editor -- Code Style -- File and Code Templates

![20171218102531141][]

模板如下，只能实现类注释，方法注释只能用live templates

/**   
     * projectName: ${PROJECT_NAME}   
     * fileName: ${NAME}.java  
     * packageName: ${PACKAGE_NAME}   
     * date: ${YEAR}-${MONTH}-${DAY} ${TIME}
     * copyright(c) 2017-2020 xxx公司  
     */  
    #if (${PACKAGE_NAME} && ${PACKAGE_NAME} != "")package ${PACKAGE_NAME};#end
    
    /**  
     * @version: V1.0  
     * @author: fendo  
     * @className: ${NAME}
     * @packageName: ${PACKAGE_NAME}  
     * @description: ${DESCRIPTION}
     * @data: ${YEAR}-${MONTH}-${DAY} ${TIME}
     **/ 
    public class ${NAME} {
    }

**3.2.1、live templates**

Live Template用中文应该叫做热加载模板。它的原理就是配置一些常用代码字母缩写，在输入简写时可以出现你预制的模板内容，使得开发效率大大提高。

在配置当中找到Live Template,右边加号先添加一个TemplateGroup

![20171218103755518][]

选中该分组再点击加号添加一个Live Template.Abbreviation中填写命令,Description填写描述,Template text填写你的配置模板。

![20171218111535275][]

代码注释模板如下:

/**   
     * @title: $file_name$
     * @package $package_name$
     * @description: 
     * @author: $author$
     * @date: $date$ $time$
     * @version: V1.0   
    */

注意:

这里的变量是$$括起来的！！

然后点击

![20171218111636031][]

选择Everywhere

![20171218111750439][]

然后选择JAVA

![20171218111820548][]

最后点击右下角的Edit variables 按钮，然后弹出一个窗口，如下：

![20171218111843536][]

注意:

默认值需要用""括起来!!

内置函数详细请参考:[https://www.jetbrains.com/help/idea/live-template-variables.html][https_www.jetbrains.com_help_idea_live-template-variables.html]

方法注释如下:

/**  
     *@title: $enclosing_method$
     *@description: TODO  
     *@author: $author$  
     *@date: $date$ $time$   
     *@param: $param$
     *@return: $return$ 
     *@throws:
     */

![20171218121844324][]

其中的param也可以使用：

groovyScript("def result=''; def params=\"${_1}\".replaceAll('[\\\\[|\\\\]|\\\\s]', '').split(',').toList(); for(i = 0; i < params.size(); i++) {result+=' * @param ' + params[i] + ((i < params.size() - 1) ? '\\n\\b' : '')}; return result", methodParameters())

这种生成的会换行。

注意:

有个很坑的地方就是，使用这个注释的时候，必须在方法内使用，如果在方法外使用有些参数就会获取不到。。。

![20171218122130212][]

不足之处:  
  
**1、live template中的函数方法是读取当前函数体的属性，所以只有在该方法内使用该命令才能获取,如果想获取其他一些信息，如项目名，字段名，根本获取不到，这是个比较鸡肋的地方。  
2、Template variables的Expression不能叠加方法。定制化程度不够好。**

IntelliJ IDEA 的实时代码模板保存在 /templates 目录下，其他系统目录位置如下：

Windows: C:\Users\xxxx\.IntelliJIdea2017.2\config
    Linux: ~/.<product name><version number>/config/templates
    OS X: ~/Library/Preferences/IdeaIC2017.2/templates

![20171218132757323][]

**一些常用的模板:**

**1.logger**

private static final Logger logger = LoggerFactory.getLogger($CLASS_NAME$.class);

**2.loggerout**

logger.info("op=start_$METHOD_NAME$, $PARAMS_FORMAT$", $PARAMS$);

**3.test**

@Test
    public void test() {
         
    }

[20171217212328913]: /images/20220603/8eb4e4f08ae248cdadbdd5d02078e34a.png
[20171217205751012]: /images/20220603/4a37a36b3f9b430da6cbe641d0ae692b.png
[20171217212638811]: /images/20220603/77e1f76ef81d4984b39495ee0b409dc3.png
[20171217211025679]: /images/20220603/3fbe5ff44a8e4177b86890bf15998f9a.png
[20171217205841671]: /images/20220603/14f716c0a91b4d4d88bbdd11d5ec8f73.png
[20171217212959927]: /images/20220603/c85ddfbe86204c909adfd54f5b072852.png
[20171218102531141]: /images/20220603/201f20cb14754fa2aa48b96a22b3d6db.png
[20171218103755518]: /images/20220603/ed57946ac4114629b140490ae376bcbe.png
[20171218111535275]: /images/20220603/945cdfcd7f0b428ebb313b29791dd31a.png
[20171218111636031]: /images/20220603/6c50422a16794cfdbb8c20030e87b1b5.png
[20171218111750439]: /images/20220603/ff3d7c3ae0ef43edabe5e6c77679f07d.png
[20171218111820548]: /images/20220603/9a49d7de0d834f739bb5f5b2ffdd66f3.png
[20171218111843536]: /images/20220603/ff60a30a2e064c059db973c2637a5d5a.png
[https_www.jetbrains.com_help_idea_live-template-variables.html]: https://www.jetbrains.com/help/idea/live-template-variables.html
[20171218121844324]: /images/20220603/7f6faebc25de48e581ac389eb2a2e1c4.png
[20171218122130212]: /images/20220603/b6a63acaf69d4030912d727d2d4e79f1.png
[20171218132757323]: /images/20220603/097be2e1d67543b9ac8610890a31c155.png