IOS Android项目注释规范

场景描述：最近整理公司开发的项目，发现公司项目很多地方写的不规范，尤其是注释；这对以后维护和开发带来了很多不便。尤其对于对项目本身不熟悉的人，在没有注释的情况下看项目会很费劲，通过代码理解开发人员的思路比较慢；但是在注释详细的情况下就能有效的帮助维护人员和后来开发人员更容易理解项目，节省时间。另一方面规范的文档同时可以帮助开发人员有效的理解自己编写的代码，防止时间长忘记。    对于公司自己积累的一些库、架包等一定要编写详细的文档，这些东西开发人员调用的时候只需要引用一下，而不必知道具体实现过程，如果没有详细的文档，开发人员根本无法使用。

代码注释这东西对于开发人员来说可能刚开始程序员很不在意这东西，认为程序都是自己开发的，根本不需要在做什么注释，纯粹是浪费时间。首先需要明白的注释是帮助自己和别人快速理解代码，刚开始的时候可能看着有点浪费时间，其实不然，这对以后不管别人还是自己项目维护，重构都有好处。

现在就针对Android、IOS项目注释问题说一下自己的看法，首先我需要声明的是我这里说的注释规范是针对能通过Eclipse、Xcode自动生成文档注释的简单规范。

1.Android项目

/**
 * 
 * @ClassName: Student 
 * 类描述: TODO(这里用一句话描述这个类的作用) 
 *
 */
public class Student {

	/**
	 *字段描述：用户id
	 */
	private String id;
	
	/**
	 * 字段描述：用户名字
	 */
	private String userName;

	/**
	 * 
	 * 方法描述：获取用户Id
	 * @return 用户id
	 */
	public String getId() {
		return id;
	}

	/**
	 * 
	 * 方法描述：设置用户Id
	 * @param id 用户id
	 */
	public void setId(String id) {
		this.id = id;
	}

	/**
	 * 
	 * 方法描述：获取用户名字 
	 * @return 用户名字
	 */
	public String getUserName() {
		return userName;
	}

	/**
	 * 
	 * 方法描述：
	 * @param userName 用户名字
	 */
	public void setUserName(String userName) {
		this.userName = userName;
	}
}

通过/***/这是注释方法，然后通过eclipse上面自带的导出Javadoc工具会自动生成html文档注释。导出方法：选中项目------》右键Export-----》Java-----》Javadoc，然后根据提示一步一步往下走就可以自动生成html文档注释。

2.IOS项目

IOS我这边推荐使用Appledoc，这样生成的注释可以直接选中一个方法，按option就可以快捷显示出描述，达到和官方文档一样的效果。

Appledoc具体使用方法您可以到https://github.com/tomaz/appledoc/blob/master/Readme.markdown查看；安装Appledoc碰到的问题，一种是终端git命令无法使用，这种情况下你可以直接下载源码编译，然后安装，第二种安装过程中你电脑的默认安装位置可能不存在，导致安装失败，这种情况下你可以通过改变默认安装位置 

sudo sh install-appledoc.sh -b /usr/bin -t ~/Library/Application\ Support/appledoc

这样安装成功后终端会显示  

Installing binary to /usr/bin

Copying templates to /Users/greentreeinn/.appledoc

这个说明你Appledoc已经安装成功，安装位置为/usr/bin/appledoc 请记住这个位置，在配Xcode的时候需要用到。

到目前位置Appledoc已经安装成功了，那怎样利用他自动生成文档注释那。在这个页面https://github.com/tomaz/appledoc/blob/master/XcodeIntegrationScript.markdown有详细的结合Xcode生成文档注释说明。这里需要说明的是Script里面

#appledoc Xcode script  
# Start constants  
company="ACME";  
companyID="com.ACME";
companyURL="http://ACME.com";
target="iphoneos";
#target="macosx";
outputPath="~/help";
# End constants
/usr/local/bin/appledoc \

上面需要根据自己的项目具体配，  最后一行是appledoc的安装位置，这个一定要搞清楚。

在IOS里面注释 我一般用 ///单行注释，主要注释一些字段和简单方法   /***/注释类、详情方法。到时候直接运行生成doc。和官方文档一样。