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。和官方文檔同樣。