生成注释_java基础- Java编程规范与注释

一前言

java编程规约是指在java代码编写过程中通俗的约定；通常我们是要遵守这些规范；这好比我们在生活中要遵守的道德准则，如果你做的事情超出了道德的底线，那就有可能会受到社会抨击；在java编程中也是类似的道理，如果你编写的代码不是很规范，尽管功能实现的功能强大，但其他java编程人员都看不懂你的代码，别人就认为你这是垃圾代码，后期的维护工作就会很艰难，而且心里肯定对你很不爽；如果在工作中遇见这种情况，你l的eader就有可能让你重写编写代码；

二命名规范

良好的代码命名规则习惯有助于我们快速浏览代码，让代码的可读性强，易于他人阅读，后期维护工作简单；

2.1 驼峰命名法

驼峰命名法（Camel-Case）是程序编程的通俗约定，其分为大驼峰写法和小驼峰写法；

大驼峰：每一个单词首字母大写，随后的字母小写；示例：ILoveJavaProgramer
小驼峰：第一个单词全小写，之后的单词首字母大写，其余字母小写；示例：iLoveJavaProgramer

2.2 包名写法

比如我有个域名是： java.com; 我现在要创建工程的包结构，那么通常包的命名规则是将域名反写，之后跟具体的包名；所有的包名都统一使用小写；

示例：com.java.zszxz.service

2.3 类名，接口名，文件名写法

类名，接口名，文件名写法统一采用大驼峰写法；

示例：

类名：FileInputStream
接口名：InputStream
文件名：UserMapper.xml

2.4 方法名,字段名写法

方法名和字段名称统一采用小驼峰命名写法；

示例：

方法名：getUser()
字段名： fieldInfomation

2.4 常量名写法

常量是特殊的字段，也就是特殊的变量，其约定的写法跟之前稍有不同，其采用的写法是所有单词的字母都大写，单词之间使用下划线隔开；

示例： I_LOVE_JAVA_PROGRAMER

三代码注释

代码的注释的作用主要是进行代码解释，类似你买了一个硬件设备，你要看说明书才知道怎么用这个设备，注释就起到了说明书的功能；代码注释的第二个功能是能注释到你当前写的代码，但后面又可能用到该代码，舍不得删除的情况；

3.1 单行注释

单行注释源于c++,其意指能注释掉一行代码，使用两个斜杆（//);

示例： // 我是知识追寻者，你是谁？觉得文章不错能帮助到你，那还不关注下？

3.2 多行注释

多行注释的风格源于c；其是斜杆和星号开头，中间部分是内容，以星号和斜杆结束（/ ............... /）；

示例： / 今天你的小伙伴来找你了吗? /

3.3 文档注释

文档注释是指能够通过jdk的javadoc命令使注释生成html帮助文档，比如开发人员常看的jdk 的 API帮助文档；使用格式是以斜杆和2个星号开头，中间是内容，以星号和斜杆结束（/* .................... /）；

通常文档注释只对 public 和 protect 级别的的成员进行注释，内部私有的成员是不提供给外部；

常用标签介绍：

了解更多标签示例请看：java文档注释

使用示例：

public class Doc {@Deprecatedprivate String buguaiguai;private String love;/*** @see        java.lang.Object#toString()* @see        java.lang.String* @see        String* {@link      System}* {@link      System#getProperties()}* <a href="{@docRoot}/java/lang/doc-files/ValueBased.html">value-based</a>* @param love  is favorite* @return the love* @deprecated <p>buguaiguai</p>* @throws RuntimeException  contribution the java world* @since  zszxz* @version 1.0.0* @author lsc/zszxz/youku1327*/public String getLove(String love){return "love";}
}

生成doc命令

javadoc -d tagerPath sourcePath/className.java

命令过程：

C:Users林>javadoc -d C:mydatageneratordoc  C:javaworkspaceforresourcestudy-01basesrcmainjavacomyouku1327basedocDoc.java
正在加载源文件C:javaworkspaceforresourcestudy-01basesrcmainjavacomyouku1327basedocDoc.java...
正在构造 Javadoc 信息...
正在创建目标目录: "C:mydatageneratordoc"
标准 Doclet 版本 1.8.0_131
正在构建所有程序包和类的树...
正在生成C:mydatageneratordoccomyouku1327basedocDoc.html...
正在生成C:mydatageneratordoccomyouku1327basedocpackage-frame.html...
正在生成C:mydatageneratordoccomyouku1327basedocpackage-summary.html...
正在生成C:mydatageneratordoccomyouku1327basedocpackage-tree.html...
正在生成C:mydatageneratordocconstant-values.html...
正在构建所有程序包和类的索引...
正在生成C:mydatageneratordocoverview-tree.html...
正在生成C:mydatageneratordocindex-all.html...
正在生成C:mydatageneratordocdeprecated-list.html...
正在构建所有类的索引...
正在生成C:mydatageneratordocallclasses-frame.html...
正在生成C:mydatageneratordocallclasses-noframe.html...
正在生成C:mydatageneratordocindex.html...
正在生成C:mydatageneratordochelp-doc.html...C:Users林>

生成结果：

四空行与缩进

4.1 空行

空行是指不同功能的代码之间要做到空行，以便于区分；

通常类名接口名，与其成员保持2个空行，如果有注释其也算一个空行；
不同类别的成员之间保持一个空行；
方法逻辑与方法名空一行；

示例：

/*
* 类的注释不需要空行
* /
public class zszxz {// 成员与类或者接口包池2个空行，包括注释；private String love;private Integer age; // 不同类别的成员保持一行private String gender;// 相同类名的成员不用空行public String getLove(){return "love"; // 方法逻辑与方法名空一行}}

4.2 缩进

类和属性；方法和逻辑；它们之间的缩进都是以4个空格为单位，可以使用制表符来代替多个空格，作者的一个制表符设置的是2个空格；

示例：

/*
* 类的开头不需要空格
* /
public class zszxz {// 成员与类或者接口保持4个空格private String love;private Integer age; // 成员与类或者接口保持4个空格private String gender;// 成员与类或者接口保持4个空格public String getLove(){ //成员与类或者接口保持4个空格return "love"; // 方法逻辑与方法名保持4个空格}}