• 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. /**  
    11.  * @version: V1.0  
    12.  * @author: fendo  
    13.  * @className: ${NAME}
    14.  * @packageName: ${PACKAGE_NAME}  
    15.  * @description: ${DESCRIPTION}
    16.  * @data: ${YEAR}-${MONTH}-${DAY} ${TIME}
    17.  **/ 
    18. public class ${NAME} {
    19. }


    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:Usersxxxx.IntelliJIdea2017.2config
    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.      
    4. }
  • 相关阅读:
    浅谈prufer编码
    数据结构训练之三
    博弈论训练之一
    动态规划训练之十三
    杂题训练之七
    奇技淫巧训练之八
    浅谈博弈论
    浅谈卡特兰数
    奇技淫巧训练之七
    浅谈概率期望的一些例题
  • 原文地址：https://www.cnblogs.com/zhuhui-site/p/10069154.html
Copyright © 2020-2023  润新知