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。和官方文档同样。