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

一、前言

好的代码规范是一个程序员的基本修炼,好的代码注释更能体现一个程序员的思维逻辑,虽然代码是用来给机器运行的,我们只要能写出能让编译器运行的代码就行了,但是如果没有好的编码规范,到项目后期,加入开发的人员逐渐增多时,每个人的编码风格都不一样,这就会让项目维护者很难维护,所以开始就要制定一些好的规范来让大家遵守,这样才能写出可维护,健壮的项目,这就是接下来要做的事情。第一节从要从代码注释这一块说起,包含: 版权注释、类注释(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 

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

1.文件(Files)注释标签:

设置版权信息:


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


注意: 要打上勾!!


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


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

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}
 */

另一类是代码模板如下:

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

完整的模板如下:



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
 


 

模板如下,只能实现类注释,方法注释只能用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

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

代码注释模板如下:


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


注意:
这里的变量是$$括起来的!!


然后点击

选择Everywhere

然后选择JAVA

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

注意:

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

内置函数详细请参考: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:
 */   


其中的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())

这种生成的会换行。


注意:

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

不足之处:

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

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


Windows: C:\Users\xxxx\.IntelliJIdea2017.2\config
Linux: ~/./config/templates
OS X: ~/Library/Preferences/IdeaIC2017.2/templates


一些常用的模板:

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() {
     
}

————————————————
版权声明:本文为CSDN博主「lfendo」的原创文章,遵循CC 4.0 BY-SA版权协议,转载请附上原文出处链接及本声明。
原文链接:https://blog.csdn.net/u011781521/article/details/78827425

你可能感兴趣的:(java)