java文档注释

文档注释(comment)：用于注解说明解释程序的文字就是注释。 

Java中的注释类型： 
         单行注释 

         多行注释 

         文档注释 (java特有) 

文档注释的好处：

        提高了代码的阅读性；调试程序的重要方法。 

        注释是一个程序员必须要具有的良好编程习惯。将自己的思想通过注释先整理出来，再用代码去体现

单行注释 
格式： //注释文字 

例子：

public static void main(String[] args) {
		int age=18; //(单行注释)声明一个int类型的变量age，并初始化为18;
	}

多行注释 
格式： /* 注释文字 */ 

例子：

public class CommentTest {
	public static void main(String[] args) {
		int age=18; //(单行注释)声明一个int类型的变量age，并初始化为18;
	}
	
	/*
	 * 多行注释：
	 * 用来检查输入的年龄是否合理，
	 * 如果输入的年龄小于0，或者大于120，返回false。
	 * 否则就返回true
	 * 
	 */
	public boolean checkAge(int age) {
		if(age<0 || age>120) {
			return false;
		}
		return true;
		
	}
}

注： 
对于单行和多行注释，被注释的文字，不会被JVM（java虚拟机）解释执行。 
多行注释里面不允许有多行注释嵌套

文档注释（Java特有） 
格式：/** 
        @author 指定java程序的作者 
        @version 指定源文件的版本 
    */ 

/**
 * 文档注释：
 * 一个用来检查年龄是否合法的类
 * 
 * @author root
 * @version 1.0.0
 *
 */
public class CommentTest {
	public static void main(String[] args) {
		int age=18; //(单行注释)声明一个int类型的变量age，并初始化为18;
	}
	
	/*
	 * 多行注释：
	 * 用来检查输入的年龄是否合理，
	 * 如果输入的年龄小于0，或者大于120，返回false。
	 * 否则就返回true
	 * 
	 */
	public boolean checkAge(int age) {
		if(age<0 || age>120) {
			return false;
		}
		return true;
		
	}
}

        注释内容可以被JDK提供的工具 javadoc 所解析，生成一套以网页文件形 
式体现的该程序的说明文档。
 
 操作方式 ：javadoc -d mydoc -author -version <文件名.java>

例子：

javadoc -d mydoc -author -version CommentTest.java

 

Java API的文档 

        API （Application Programming Interface,应用程序编程接口）是 Java 提供的基本编程接口

Java语言提供了大量的基础类，因此 Oracle 也为这些基础类提供了相应的API文档，用于告诉开发者如何使用这些类，以及这些类里包含的方法。 

下载API： 
        http://www.oracle.com/technetwork/java/javase/downloads/index.html
        AdditionalResources-Java SE 8 Documentation下载。 

良好的编程风格 
         正确的注释和注释风格 
         使用文档注释来注释整个类或整个方法。
         如果注释方法中的某一个步骤，使用单行或多行注释。

正确的缩进和空白 
     使用一次tab操作，实现缩进运算符两边习惯性各加一个空格。比如：2 + 4 * 5。 

 块的风格 

         Java API 源代码选择了行尾风格

行尾风格

public class TestHello {                        
    public static void main(String[] args) {   
        System.out.println("hello，world");   
    }                                          
}   

           
次行风格

public class TestHello                          
{                                               
    public static void main(String[] args)     
    {                                          
        System.out.println("hello，world");   
    }                                          
}