java开发注释规范规范

javadoc 是j2sdk里面一个非常重要的工具，如果你按照规范在java的源代码里面写好注释的话，那么它就可以生成相应的文档。

开发者察看起来会非常方便。

很多IDE都可以直接生成javadoc的，这里介绍如何写javadoc以及如何在eclipse下生成javadoc。

javadoc通常从package、公开类或者接口、公开或者受保护的字段、公开或者受保护的方法提取信息。

每条注释应该是以/**开始以*/结尾。

例如
/**
*
* @param id the coreID of the person
* @param userName the name of the person
* you should use the constructor to create a person object
*/
public SecondClass(int id,String userName)
{
this.id = id;
erName = userName;
}
注释应该写在要说明部分的前面，如上所示。

并且在其中可以包括html的标记，如果上面没有标记的话，那么you should usr the ......将会在javadoc里面紧跟@param userName....，这样不是我们希望的。

一般注释可以分为类注释、方法注释、字段注释等。

下面分别作简单的介绍
类注释
类注释应该在import语句的后面在类声明的前面，比如
package com.north.java;
/**
* @author ming
*
* this interface is to define a method print()
* you should implements this interface is you want to print the username
* @see com.north.ming.MainClass#main(String[])
*/
public interface DoSomething
{
/**
* @param name which will be printed
* @return nothing will be returned
*
*/
public void print(String name);
}
其中@author 和@see都是常用的注释第一个表示作者，第二个表示参考的连接。

2.方法注释
方法注释要紧靠方法的前面，你可以在其中使用@param @return @throws等标签。

例如
/**
*
* @param i
* @return true if ..... else false
* @throws IOException when reading the file ,if something wrong happened
* then the method will throws a IOException
*/
public boolean doMethod(int i) throws IOException
{
return true;
}
3.字段注释
只有public的字段才需要注释，通常是static德，例如
/**
* the static filed hello
*/
public static int hello = 1;
在eclipse中我们新建java project然后编写几个接口和类以后就可以用javadoc生成文档了，从菜单project选择generate javadoc，会出现一个向导，你按照他的提示一步一步的设定要求，最好他会问你是不是声称一个javadoc.xml，如果选择生成的话，他会在doc 下产生一个javadoc.xml，以后更新文档的时候你可以直接用ant运行javadoc.xml。

选择完成后你可以发现在project里面出现了一个目录doc里面就是你的javadoc,想写出好的javadoc 一个非常好的办法就是多参考java的api doc。

养成一个好的编程习惯非常重要，何况这并不难。

下面是我写着篇blog的代码和注释
/*
* Created on 2004-7-25
*
* TODO To change the template for this generated file go to
* Window - Preferences - Java - Code Style - Code Templates
*/
package com.north.ming;
/**
* @author P2800
*
* TODO To change the template for this generated type comment go to * Window - Preferences - Java - Code Style - Code Templates
*/
public class MainClass
{
public static void main(String[] args)
{
}
}
/*
* Created on 2004-7-25
*
* TODO To change the template for this generated file go to
* Window - Preferences - Java - Code Style - Code Templates
*/
package com.north.ming;
import java.io.IOException;
/**
* @author P2800
*
* TODO To change the template for this generated type comment go to * Window - Preferences - Java - Code Style - Code Templates
*/
public class SecondClass
{
/**
* the static filed hello
*/
public static int hello = 1;
private int id;
private String userName;
/**
*
* @param id the coreID of the person
* @param userName the name of the person
* you should use the constructor to create a person object
*/
public SecondClass(int id,String userName)
{
this.id = id;
erName = userName;
}
/**
* @return Returns the userName.
*/
public String getUserName()
{
return userName;
}
/**
* @param userName The userName to set.
*/
public void setUserName(String userName)
{
erName = userName;
}
/**
*
* @param i
* @return true if ..... else false
* @throws IOException when reading the file ,if something wrong happened * then the method will throws a IOException
*/
public boolean doMethod(int i) throws IOException
{
return true;
}
}
/*
* Created on 2004-7-25
*
* TODO To change the template for this generated file go to
* Window - Preferences - Java - Code Style - Code Templates
*/
package com.north.java;
/**
* @author ming
*
* this interface is to define a method print()
* you should implements this interface is you want to print the username
* @see com.north.ming.MainClass#main(String[])
*/
public interface DoSomething
{
/**
* @param name which will be printed
* @return nothing will be returned
*
*/
public void print(String name);
}。