1、前言html
好的代码规范是一个程序员的基本修炼,好的代码注释更能体现一个程序员的思惟逻辑,虽然代码是用来给机器运行的,咱们只要能写出能让编译器运行的代码就好了,可是若是没有好的编码规范,到项目后期,加入开发的人员逐渐增多时,每一个人的编码风格都不同,这就会让项目维护者很难维护,因此开始就要制定一些好的规范来让你们遵照,这样才能写出可维护,健壮的项目,这就是接下来要作的事情。第一节从要从代码注释这一块提及,包含: 版权注释、类注释(Class)、构造函数注释(Constructor)、方法注释(Methods)、代码块注释(Block)、单句注释、字段名注释,而后分别为eclipse、IDEA建立注释模块等。java
2、约定程序员
下面就是一些常见的注释示例:eclipse
一、版权注释ide
版权注释主要用来声明公司的一些基本信息等:函数
/** * projectName: xxx * fileName: Tk.java * packageName: xxxx * date: 2017年12月18日下午12:28:39 * copyright(c) 2017-2020 xxx公司 */
二、类注释(Class)ui
类注释(Class)主要用来声明该类用来作什么,以及建立者、建立日期版本、包名等一些信息:编码
/** * @version: V1.0 * @author: fendo * @className: user * @packageName: user * @description: 这是用户类 * @data: 2017-07-28 12:20 **/
三、构造函数注释(Constructor)idea
构造函数注释(Constructor)主要用来声明该类的构造函数、入参等信息:spa
** * @description: 构造函数 * @param: [sid, pid] */
四、方法注释(Methods)
方法注释(Methods)主要用来声明该类的做用、入参、返回值、异常等信息:
/** * @author: fendo * @methodsName: addUser * @description: 添加一个用户 * @param: xxxx * @return: String * @throws: */
五、代码块注释(Block)
/** * 实例化一个用户 * xxxxxxx */ User user=new User();
六、单句注释
User user=new User(); //实例化一个用户
七、字段名注释
/** * 用户名 */ public String name;
或者使用以下格式:
/**用户名**/ public String name;
3、IDE模板
接下来就是分别在Eclipse和IDEA中实现上面的注释,而后分别生成模板:
3.一、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: */
/** *@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} */
因为基本的在上面的已经设置好了,因此这里也不须要设置什么,而后就是把这个模板导出来,分发给各开发人员,让他们导进来就好了。
完整的模板以下:
<?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.二、IDEA代码注释
idea有两种快捷方式,一个是live templates,一个是file and code templates。
3.2.一、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.一、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())
注意:
有个很坑的地方就是,使用这个注释的时候,必须在方法内使用,若是在方法外使用有些参数就会获取不到。。。
不足之处:
一、live template中的函数方法是读取当前函数体的属性,因此只有在该方法内使用该命令才能获取,若是想获取其余一些信息,如项目名,字段名,根本获取不到,这是个比较鸡肋的地方。
二、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
一些经常使用的模板:
1.logger
private static final Logger logger = LoggerFactory.getLogger($CLASS_NAME$.class);
logger.info("op=start_$METHOD_NAME$, $PARAMS_FORMAT$", $PARAMS$);
@Test public void test() { }