基本上一個優良的程式撰寫風格就是最直接的說明文件, 不過這裡不辯證該不該寫註解的問題, 另外, 程式內的註解與系統文件還是有所差異, 其對象及目的也有所不同, 在此也不討論 :
註解的種類有 :
1.
repeat of the code : 就是用口語將程式重複說一遍, 像是給不懂程式語言的人看的
2.
explanation of the code : 用來解釋一些複雜或高技巧的程式, 不過往往是撰些時沒有注意程式的結構, 才會如此難懂, 不如用心思再將這段程式改寫的可讀性更高一些, 有關如何寫出優良的程式, 應該有不少書談論
3.
marker in the code : 程式設計師以特殊的標記如 /* %%Note%% ….. */ 留下暫時的標記, 以方便紀錄程式設計過程中, 未完成或待加強的部分
4.
summary of the code : 只取某段程式碼中的重點, 以兩三句話說明, 比重複整段程式來的有用多了
5.
description of the code’s
intent : 解釋一段程式的目的, 不從技術面說明, 程式開頭的說明也是這類
如果在分析設計階段能用Pesudo
Code或PDL(Program
Design Language), 在實作階段在加入程式碼, 那麼這些PDL就是最佳的程式內註解, 不過PDL也有一定撰寫的規則的
關於第二點，有些不同的看法:
回覆刪除>> 2. explanation of the code : 用來解釋一些複雜或高技巧的程式, 不過往往是撰些時沒有注意程式的結構, 才會如此難懂, 不如用心思再將這段程式改寫的可讀性更高一些, 有關如何寫出優良的程式, 應該有不少書談論。
舉個例子來說明:
學過 algorithm 的人應該都知道,多項式 a+b*x+c*x**2+d*x**3 的計算,應該使用a+x*(b+x*(c+x*d)) 才比較有效率。可是我遇到很人,看到這樣的算法時根本沒辦法理解,這時如沒有加上註解還常常被強迫改寫。
也就是說勉強要求程式易懂,就變成要犧牲程式的效率。