程式內的註解要寫些什麼?

fredwang(王富民)
2003/02/27

基本上一個優良的程式撰寫風格就是最直接的說明文件, 不過這裡不辯證該不該寫註解的問題, 另外, 程式內的註解與系統文件還是有所差異, 其對象及目的也有所不同, 在此也不討論

註解的種類有
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也有一定撰寫的規則的