?
方法的注釋
:
1.????????
清楚地表述出方法的功能，即該方法做什么。不用表述怎么做（怎么做是算法層面的東西，如果算法有一定的復(fù)雜度，在其它文檔表述，如流程圖、算法、序列圖等）。注意點是：方法可能實現(xiàn)多個相關(guān)功能，要表述每個功能的激活條件（即輸入?yún)?shù)的特征），及相應(yīng)的功能。
若該方法與其它若干個方法相關(guān)，要將它們的關(guān)聯(lián)性表述出來，這對于理解整個類的行為很關(guān)鍵。特別是，當(dāng)對象有狀態(tài)時，這時該方法的調(diào)用可能要依賴于其它方法的先行調(diào)用（即對象的當(dāng)前狀態(tài)），對象的狀態(tài)改變及方法的依賴關(guān)系是必須描述清楚的。
?
方法的功能點是指外部可觀察的行為：如方法的返回值；方法做的日志；如果有輸入?yún)?shù)，方法的輸入
—
〉返回的對應(yīng)關(guān)系；產(chǎn)生的異常及其原因；方法的前置依賴；方法造成的對象狀態(tài)改變（后置狀態(tài)）等。
?
輸入?yún)?shù)的有效性要表述嗎？異常需要表述嗎
?
視情況而定，如果情況復(fù)雜，特別是異常的產(chǎn)生的原因復(fù)雜，需要較多的話才能表述清楚，就需要表述。
?
2.????????
輸入?yún)?shù)：包括參數(shù)的含義，及有效性格式。如果某個參數(shù)的有效性方法內(nèi)部不作檢查，要清晰地說明，這意味著調(diào)用者自己要保證參數(shù)的有效性，不然會造成不確定的錯誤。通常，這種情況出現(xiàn)在從外部傳入大量的數(shù)據(jù)，并且對數(shù)據(jù)有效性檢查很煩瑣，這時可以在系統(tǒng)入口進(jìn)行有效性檢查，系統(tǒng)內(nèi)部的方法就不再進(jìn)行檢查了。
3.????????
返回參數(shù)：包括參數(shù)的含義，可能會有多個不同的返回值，通常是一個有效返回和一個異常返回，對于異常返回，要表述其對應(yīng)的輸入?yún)?shù)。
4.????????
拋出異常：表述產(chǎn)生各個異常產(chǎn)生的原因。
?
表述的清晰性檢查：
1．?
用舉例來輔助說明一些文字表述較困難的思想
2．?
要注意分段，跟寫文章一樣，當(dāng)注釋很長時，要有分段。
3．?
與單元測試對應(yīng)性，方法的每個功能點都應(yīng)該有相應(yīng)的單元測試對應(yīng)
4．?
方法之間的依賴關(guān)系也是功能點，應(yīng)該有相應(yīng)的單元測試。
?
?
單元測試的注釋：
1
．測試函數(shù)名：
test+
方法名
+
分類
+
數(shù)字編號，分類是
Right-Correct
的全稱，數(shù)字編號是該分類的測試用例編號。如測試
mutiple
的一個測試函數(shù)可命名為
testMultipleRight1
。
?
2
．
描述：測試哪個功能點？測試哪個參數(shù)有效性格式？測試哪個方法依賴性？測試哪個異常？（這些與方法的注釋對應(yīng)）
??????
輸入?yún)?shù)：
輸出結(jié)果：
??????
?當(dāng)被測試方法的輸入、輸出不那么明顯時，也就是說可能沒有輸入?yún)?shù)或者沒有返回值時，輸入、輸出中則視情況而寫。
輸入：為測試準(zhǔn)備的前提條件（可以是事件）。
輸出：?測試期望得到的結(jié)果，不一定是返回值。
?
?
?
|