Java命名、注释规范

一、命名规范

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创建注释模块等。


二、约定

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

其中 /** */注释和 /* */注释 的区别:

/** */注释的话,你再调用类和方法的时候会出现提示,内容就是你写的注释。就好像文档帮助一样。类似"字符串".toString(),鼠标放在toString()上时出现的api说明。 而/* */就没有了。 /* */就是//的多行版


1、版权注释

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

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


2、类注释(Class)

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

  1. /**
  2. * @version: V1.0
  3. * @author: fendo
  4. * @className: user
  5. * @packageName: user
  6. * @description: 这是用户类
  7. * @data: 2017-07-28 12:20
  8. **/


3、构造函数注释(Constructor)

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

  1. **
  2. * @description: 构造函数
  3. * @param: [sid, pid]
  4. */


4、方法注释(Methods)

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

  1. /**
  2. * @author: fendo
  3. * @methodsName: addUser
  4. * @description: 添加一个用户
  5. * @param: xxxx
  6. * @return: String
  7. * @throws:
  8. */

5、代码块注释(Block)

  1. /**
  2. * 实例化一个用户
  3. * xxxxxxx
  4. */
  5. User user=new User();


6、单句注释

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

7、字段名注释

  1. /**
  2. * 用户名
  3. */
  4. public String name;

或者使用如下格式:

  1. /**用户名**/
  2. public String name;


三、IDE模板


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


3.1、Eclipse代码注释


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



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




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


设置版权信息:

  1. /**
  2. * projectName: ${project_name}
  3. * fileName: ${file_name}
  4. * packageName: ${package_name}
  5. * date: ${date}${time}
  6. * copyright(c) 2017-2020 xxx公司
  7. */



注意: 要打上勾!!


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

  1. /**
  2. * @title: ${file_name}
  3. * @package ${package_name}
  4. * @description: ${todo}
  5. * @author: fendo
  6. * @date: ${date} ${time}
  7. * @version: V1.0
  8. */



3.字段(Fields)注释标签:

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

4.构造函数(Constructors)标签:

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


5.方法(Methods)标签:

  1. /**
  2. *@title: ${enclosing_method}
  3. *@description: ${todo}
  4. *@author: fendo
  5. *@date: ${date} ${time}
  6. *${tags}
  7. *@throws:
  8. */

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

  1. /**
  2. * @title: ${enclosing_method}
  3. * @description: ${todo}
  4. * ${tags}
  5. * ${see_to_overridden}
  6. */

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

  1. /**
  2. * ${tags}
  3. * ${see_to_target}
  4. */

8.Getter方法标签:

  1. /**
  2. * @title: ${enclosing_method}
  3. * @description: ${todo}
  4. * @return: ${field_type}
  5. */

9.Setter方法标签:

  1. /**
  2. * @title: ${enclosing_method}
  3. * @description: ${todo}
  4. * @return: ${field_type}
  5. */

另一类是代码模板如下:



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




完整的模板如下:

  1. <?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">/**
  2. * @title: ${enclosing_method}
  3. * @description: ${todo}
  4. * @return: ${field_type}
  5. */ </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">/**
  6. * @title: ${enclosing_type}
  7. * @description: ${todo}
  8. * @param: ${tags}
  9. * @throws
  10. */ </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">/**
  11. * projectName:${project_name}
  12. * fileName:${file_name}
  13. * packageName:${package_name}
  14. * date:${date}${time}
  15. * copyright(c) 2017-2020 xxx公司
  16. */</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">/**
  17. * @title: ${file_name}
  18. * @package ${package_name}
  19. * @description: ${todo}
  20. * @author: fendo
  21. * @date: ${date} ${time}
  22. * @version: V1.0
  23. */</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">/**
  24. *@title ${enclosing_method}
  25. *@description: ${todo}
  26. *@author: fendo
  27. *@date: ${date} ${time}
  28. *${tags}
  29. *@throws
  30. */ </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">/**
  31. * @title: ${enclosing_method}
  32. * @description: ${todo}
  33. * ${tags}
  34. * ${see_to_overridden}
  35. */ </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">/**
  36. * @title: ${enclosing_method}
  37. * @description: ${todo}
  38. * @return: ${field_type}
  39. */</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">/**
  40. * @Fields ${field} : ${todo}
  41. */ </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">/**
  42. * ${tags}
  43. * ${see_to_target}
  44. */ </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

  1. /**
  2. * projectName: ${PROJECT_NAME}
  3. * fileName: ${NAME}.java
  4. * packageName: ${PACKAGE_NAME}
  5. * date: ${YEAR}-${MONTH}-${DAY} ${TIME}
  6. * copyright(c) 2017-2020 xxx公司
  7. */
  8. #if (${PACKAGE_NAME} && ${PACKAGE_NAME} != "")package ${PACKAGE_NAME};#end
  9. /**
  10. * @version: V1.0
  11. * @author: fendo
  12. * @className: ${NAME}
  13. * @packageName: ${PACKAGE_NAME}
  14. * @description: ${DESCRIPTION}
  15. * @data: ${YEAR}-${MONTH}-${DAY} ${TIME}
  16. **/
  17. public class ${NAME} {
  18. }


3.2.1、live templates


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


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



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




代码注释模板如下:

  1. /**
  2. * @title: $file_name$
  3. * @package $package_name$
  4. * @description:
  5. * @author: $author$
  6. * @date: $date$ $time$
  7. * @version: V1.0
  8. */


注意:

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

然后点击




选择Everywhere




然后选择JAVA




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




注意:

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


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


方法注释如下:

  1. /**
  2. *@title: $enclosing_method$
  3. *@description: TODO
  4. *@author: $author$
  5. *@date: $date$ $time$
  6. *@param: $param$
  7. *@return: $return$
  8. *@throws:
  9. */



其中的param也可以使用:

  1. 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 目录下,其他系统目录位置如下:

  1. Windows: C:\Users\xxxx\.IntelliJIdea2017.2\config
  2. Linux: ~/.<product name><version number>/config/templates
  3. 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

  1. @Test
  2. public void test() {
  3. }


posted @ 2018-12-05 09:38  学不死的程序员  阅读(4980)  评论(0编辑  收藏  举报