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 级别的的成员进行注释,内部私有的成员是不提供给外部;
常用标签介绍:
@see | 引用其他类,使用方式: @see className, @see className#MethodName ,@see qualifiedClassName |
@link | 引用其他类,使用方式: |
@docRoot | 生成文档的相对路径通常和a标签混用,使用方式: |
@version | 工程的版本信息,使用方式: |
@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 空行
空行是指不同功能的代码之间要做到空行,以便于区分;
- 通常类名接口名,与其成员保持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个空格
}
}