一、命名规范
1、 项目名全部小写
2、 包名全部小写
3、 类名首字母大写,如果类名由多个单词组成,每个单词的首字母都要大写。
如:public class MyFirstClass{}
4、 变量名、方法名首字母小写,如果名称由多个单词组成,每个单词的首字母都要大写。
如:int index=0;
5、 常量名全部大写
如:public static final String GAME_COLOR=”RED”;
6、所有命名规则必须遵循以下规则:
1)、名称只能由字母、数字、下划线、$符号组成
2)、不能以数字开头
3)、名称不能使用JAVA中的关键字。
4)、坚决不允许出现中文及拼音命名。
二、注释规范
好的代码规范是一个程序员的基本修炼,好的代码注释更能体现一个程序员的思维逻辑,虽然代码是用来给机器运行的,我们只要能写出能让编译器运行的代码就行了,但是如果没有好的编码规范,到项目后期,加入开发的人员逐渐增多时,每个人的编码风格都不一样,这就会让项目维护者很难维护,所以开始就要制定一些好的规范来让大家遵守,这样才能写出可维护,健壮的项目,这就是接下来要做的事情。第一节从要从代码注释这一块说起,包含: 版权注释、类注释(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}</div></div></li><li><div class="hljs-ln-numbers"><div class="hljs-ln-line hljs-ln-n" data-line-number="6"></div></div><div class="hljs-ln-code"><div class="hljs-ln-line"> *\){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} </div></div></li><li><div class="hljs-ln-numbers"><div class="hljs-ln-line hljs-ln-n" data-line-number="9"></div></div><div class="hljs-ln-code"><div class="hljs-ln-line"> * @throws </div></div></li><li><div class="hljs-ln-numbers"><div class="hljs-ln-line hljs-ln-n" data-line-number="10"></div></div><div class="hljs-ln-code"><div class="hljs-ln-line"> */ <span class="hljs-tag"></<span class="hljs-name">template</span>></span><span class="hljs-tag"><<span class="hljs-name">template</span> <span class="hljs-attr">autoinsert</span>=<span class="hljs-string">"false"</span> <span class="hljs-attr">context</span>=<span class="hljs-string">"filecomment_context"</span> <span class="hljs-attr">deleted</span>=<span class="hljs-string">"false"</span> <span class="hljs-attr">description</span>=<span class="hljs-string">"Comment for created Java files"</span> <span class="hljs-attr">enabled</span>=<span class="hljs-string">"true"</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"org.eclipse.jdt.ui.text.codetemplates.filecomment"</span> <span class="hljs-attr">name</span>=<span class="hljs-string">"filecomment"</span>></span>/** </div></div></li><li><div class="hljs-ln-numbers"><div class="hljs-ln-line hljs-ln-n" data-line-number="11"></div></div><div class="hljs-ln-code"><div class="hljs-ln-line"> * projectName:\){project_name}
-
* fileName:
\({file_name} </div></div></li><li><div class="hljs-ln-numbers"><div class="hljs-ln-line hljs-ln-n" data-line-number="13"></div></div><div class="hljs-ln-code"><div class="hljs-ln-line"> * 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}</div></div></li><li><div class="hljs-ln-numbers"><div class="hljs-ln-line hljs-ln-n" data-line-number="28"></div></div><div class="hljs-ln-code"><div class="hljs-ln-line"> *\){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
模板如下,只能实现类注释,方法注释只能用live templates
/ * projectName: ${PROJECT_NAME} * fileName: ${NAME}.java * packageName: ${PACKAGE_NAME} * date: \({YEAR}-\){MONTH}-${DAY} \({TIME}</div></div></li><li><div class="hljs-ln-numbers"><div class="hljs-ln-line hljs-ln-n" data-line-number="6"></div></div><div class="hljs-ln-code"><div class="hljs-ln-line"> * copyright(c) 2017-2020 xxx公司 </div></div></li><li><div class="hljs-ln-numbers"><div class="hljs-ln-line hljs-ln-n" data-line-number="7"></div></div><div class="hljs-ln-code"><div class="hljs-ln-line"> */ </div></div></li><li><div class="hljs-ln-numbers"><div class="hljs-ln-line hljs-ln-n" data-line-number="8"></div></div><div class="hljs-ln-code"><div class="hljs-ln-line">#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 <span class="hljs-tag">< <span class="hljs-attr">params.size</span>(); <span class="hljs-attr">i</span>++) {<span class="hljs-attr">result</span>+=<span class="hljs-string">' * @param '</span> + <span class="hljs-attr">params</span>[<span class="hljs-attr">i</span>] + ((<span class="hljs-attr">i</span> < <span class="hljs-attr">params.size</span>() <span class="hljs-attr">-</span> <span class="hljs-attr">1</span>) ? '\\<span class="hljs-attr">n</span>\\<span class="hljs-attr">b</span>' <span class="hljs-attr">:</span> '')}; <span class="hljs-attr">return</span> <span class="hljs-attr">result</span>", <span class="hljs-attr">methodParameters</span>())</span></div></div></li><li><div class="hljs-ln-numbers"><div class="hljs-ln-line hljs-ln-n" data-line-number="2"></div></div><div class="hljs-ln-code"><div class="hljs-ln-line"></div></div></li></ol></code><div class="hljs-button" data-title="复制"></div></pre><br> 这种生成的会换行。 <p></p> <p><span><span style="font-size:18px;"><span><span style="color:rgb(47,47,47);"><span style="font-size:18px;color:rgb(47,47,47);"><span style="color:rgb(47,47,47);font-size:18px;"><br></span></span></span></span></span></span></p> <p><span><span style="font-size:18px;"><span><span style="color:rgb(47,47,47);"><span style="font-size:18px;color:rgb(47,47,47);"><span style="color:rgb(47,47,47);font-size:18px;">注意:</span></span></span></span></span></span></p> <p><span><span style="font-size:18px;"><span><span style="color:rgb(47,47,47);"><span style="font-size:18px;color:rgb(47,47,47);"><span style="color:rgb(47,47,47);font-size:18px;"><br></span></span></span></span></span></span></p> <p><span><span style="font-size:18px;"><span><span style="color:rgb(47,47,47);"><span style="font-size:18px;color:rgb(47,47,47);"><span style="color:rgb(47,47,47);font-size:18px;">有个很坑的地方就是,使用这个注释的时候,必须在方法内使用,如果在方法外使用有些参数就会获取不到。。。</span></span></span></span></span></span></p> <p><span><span style="font-size:18px;"><span><span style="color:rgb(47,47,47);"><span style="font-size:18px;color:rgb(47,47,47);"><span style="color:rgb(47,47,47);font-size:18px;"><img src="https://img-blog.csdn.net/20171218122130212" alt=""><br></span></span></span></span></span></span></p> <p><span><span style="font-size:18px;"><span><span style="color:rgb(47,47,47);"><span style="font-size:18px;color:rgb(47,47,47);"><span style="color:rgb(47,47,47);font-size:18px;"><br></span></span></span></span></span></span></p> <p><span><span style="font-size:18px;"><span><span style="color:rgb(47,47,47);"><span style="font-size:18px;color:rgb(47,47,47);"><span style="color:rgb(47,47,47);font-size:18px;">不足之处:<br><br><strong>1、live template中的函数方法是读取当前函数体的属性,所以只有在该方法内使用该命令才能获取,如果想获取其他一些信息,如项目名,字段名,根本获取不到,这是个比较鸡肋的地方。<br> 2、Template variables的Expression不能叠加方法。定制化程度不够好。</strong><br></span></span></span></span></span></span></p> <p><span><span style="font-size:18px;"><span><span style="color:rgb(47,47,47);"><span style="font-size:18px;color:rgb(47,47,47);"><span style="color:rgb(47,47,47);font-size:18px;"><br></span></span></span></span></span></span></p> <p><span style="color:#2f2f2f;"><span style="font-size:18px;">IntelliJ IDEA 的实时代码模板保存在 /templates 目录下,其他系统目录位置如下:<br><br></span></span></p><pre onclick="hljs.copyCode(event)"><code class="language-html hljs xml"><ol class="hljs-ln"><li><div class="hljs-ln-numbers"><div class="hljs-ln-line hljs-ln-n" data-line-number="1"></div></div><div class="hljs-ln-code"><div class="hljs-ln-line">Windows: C:\Users\xxxx\.IntelliJIdea2017.2\config</div></div></li><li><div class="hljs-ln-numbers"><div class="hljs-ln-line hljs-ln-n" data-line-number="2"></div></div><div class="hljs-ln-code"><div class="hljs-ln-line">Linux: ~/.<span class="hljs-tag"><<span class="hljs-name">product</span> <span class="hljs-attr">name</span>></span><span class="hljs-tag"><<span class="hljs-name">version</span> <span class="hljs-attr">number</span>></span>/config/templates</div></div></li><li><div class="hljs-ln-numbers"><div class="hljs-ln-line hljs-ln-n" data-line-number="3"></div></div><div class="hljs-ln-code"><div class="hljs-ln-line">OS X: ~/Library/Preferences/IdeaIC2017.2/templates</div></div></li></ol></code><div class="hljs-button" data-title="复制"></div></pre><br><img src="https://img-blog.csdn.net/20171218132757323" alt=""><br><p><span><span style="font-size:18px;"><span><span style="color:rgb(47,47,47);"><span style="font-size:18px;color:rgb(47,47,47);"><span style="color:rgb(47,47,47);font-size:18px;"><br></span></span></span></span></span></span></p> <p><span style="font-size:18px;color:#2f2f2f;"><strong>一些常用的模板:</strong></span></p> <p><span style="font-size:18px;color:#2f2f2f;"><br></span></p> <p><span style="color:rgb(47,47,47);"><span style="font-size:18px;"><strong>1.logger</strong></span></span></p> <p><span style="font-size:18px;color:#2f2f2f;"></span></p> <pre onclick="hljs.copyCode(event)"><code class="language-html hljs xml">private static final Logger logger = LoggerFactory.getLogger(\)CLASS_NAME\(.class);</code><div class="hljs-button" data-title="复制"></div></pre><br><span style="font-size:18px;"><strong>2.loggerout</strong></span> <p></p> <p><span style="font-size:18px;color:#2f2f2f;"></span></p> <pre onclick="hljs.copyCode(event)"><code class="language-html hljs xml">logger.info("op=start_\)METHOD_NAME$, \(PARAMS_FORMAT\)", \(PARAMS\));
3.test
-
@Test
-
public void test() {
-
-
}
</div