java基础- Java编程规范与注释

一 前言

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

二 命名规范

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

2.1 驼峰命名法

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

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

2.2 包名写法

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

示例：com.java.zszxz.service

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

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

示例：

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

2.4 方法名,字段名写法

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

示例：

1. 方法名：getUser()
2. 字段名： fieldInfomation

2.4 常量名写法

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

示例： I_LOVE_JAVA_PROGRAMER

三 代码注释

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

3.1 单行注释

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

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

3.2 多行注释

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

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

3.3 文档注释

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

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

常用标签介绍：

@see	引用其他类,使用方式： @see className, @see className#MethodName ，@see qualifiedClassName
@link	引用其他类,使用方式： {@link className, @link className#methodName}
@docRoot	生成文档的相对路径通常和a标签混用，使用方式：{@docRoot /path/childPath/**.thml}
@version	工程的版本信息，使用方式：{@vsersion information}
@param	方法参数说明，使用方式： @param paramName
@return	方法的返回值，使用方式：@return information
@deprecated	类，成员或者接口已过时，不久就会被废弃 ，使用方式 ：@deprecated information
@throws	抛出的异常，使用方式 @throws ExceptionClassName
@since	文档标题，使用方式 @since information
@author	作者信息，使用方式 @author information

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

使用示例：

public class Doc {

    @Deprecated
    private 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:\mydata\generator\doc  C:\java\workspaceforresource\study-01\base\src\main\java\com\youku1327\base\doc\Doc.java
正在加载源文件C:\java\workspaceforresource\study-01\base\src\main\java\com\youku1327\base\doc\Doc.java...
正在构造 Javadoc 信息...
正在创建目标目录: "C:\mydata\generator\doc\"
标准 Doclet 版本 1.8.0_131
正在构建所有程序包和类的树...
正在生成C:\mydata\generator\doc\com\youku1327\base\doc\Doc.html...
正在生成C:\mydata\generator\doc\com\youku1327\base\doc\package-frame.html...
正在生成C:\mydata\generator\doc\com\youku1327\base\doc\package-summary.html...
正在生成C:\mydata\generator\doc\com\youku1327\base\doc\package-tree.html...
正在生成C:\mydata\generator\doc\constant-values.html...
正在构建所有程序包和类的索引...
正在生成C:\mydata\generator\doc\overview-tree.html...
正在生成C:\mydata\generator\doc\index-all.html...
正在生成C:\mydata\generator\doc\deprecated-list.html...
正在构建所有类的索引...
正在生成C:\mydata\generator\doc\allclasses-frame.html...
正在生成C:\mydata\generator\doc\allclasses-noframe.html...
正在生成C:\mydata\generator\doc\index.html...
正在生成C:\mydata\generator\doc\help-doc.html...

C:\Users\林>

生成结果：

四 空行与缩进

4.1 空行

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

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

示例：

/*
* 类的注释不需要空行
* /
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个空格
	}

}