Code規範與文檔

無規距不成方圓, 有規距自成方圓.(規距不能亂也!)
  • Code 要有閱讀的價值, 不只是對編譯器(Compiler)有意義, 更應該對人有意義。
    • - Gregor Hohpe, Enterprise Integration Patterns
  • 任何一個傻瓜都能寫出機器能懂的Code, 好的程式員應該寫出人能懂的Code。
    • - Martin Fowler, Refacing 
Code 的價值除了來自平時的自我精鍊, 盡可能於 Code 的本身傳達易懂的訊息給其它參與或將來可能參與的團隊者, 甚至是遺產系統, 寫出來的 Code 能否在未來的15年、20年甚至30年裡依舊運行如初( Code 是我的遺產,它必須一直運行下去,所以當我在幾個月後回頭看看自己所寫的 Code ,我不得不說:
"當時那傢伙在想些什麼呀!而我就是這堆 Code 的作者。"




編碼一致性



Google 很重視代碼風格的一致性,而且還公開過一份 JavaScript 代碼風格指南: Google JavaScript Style Guide,現在它們又發佈了一個工具來幫助你檢查 JavaScript 代碼是否嚴格遵循了 Google JavaScript Style Guide :Closure Linter。



程序說明文檔(JavaDoc)




  • 糟糕的註釋毫無意義
    • 註釋應該是註釋Why,而不是How和What,就像《程序員的十大技術煩惱》中所說,代碼告訴你How,而註釋應該告訴你Why。但大多數的程序並不知道什麼是好的註釋,那些註釋其實和Code是重複的,毫無意義。

方與圓~規距不能亂!





JDK API 參考文檔下載





團隊開發程式撰寫慣例公約


這不會造成Java程式的錯誤, 但卻是Teamwork的良好公約的慣例.

專案開發團隊Code的格式化與Comments應當保持最高度的一致性
  1. Teamwork風格的一致性.
  2. 減少因Code的格式造成的問題率.


Teamwork Code撰寫基本守則


  1. 適當的排版內容很重要
  2. 養成寫註解的好習慣
  3. 對於命名約定嚴格的遵守


http://www.javaworld.com.tw/jute/post/view?bid=20&id=27897&sty=1&tpg=1&age=0



JavaBean Naming Rules


for Listener
  • public void add<ListenerType>(<ListenerType> listener)
  • public void remove<ListenerType>(<ListenerType> listener)






How to Write Doc Comments for the Javadoc Tool - Sun

Javadoc Comments
http://javaworkshop.sourceforge.net/chapter4.html


Sun API 文檔社區

DocWeb Community


  • IT人甘苦談:用文件協助軟體專案管理的祕訣 文/林郁翔 2009-05-29
    • 留下詳細文件供後人維護,是每個開發團隊應負起的責任
      • 除了在需求確認要有詳細文件記載外,程式開發過程還需要在每個環節,充分製作文件記錄,如編撰機能設計書,確認系統整體結構呈現。如果在開發過程中,有詳 實的結構文件輔助,就能於功能調整中,找出各個程式間的關聯,日後修改時就可以針對這些異動一起調整,減少程式連帶產生的問題。

Comments