Code規範與文檔

Contents

  1. 1 編碼一致性
    1. 1.1 Google 發佈 Closure Linter
  2. 2 程序說明文檔(JavaDoc)
    1. 2.1 JDK API 參考文檔下載
  3. 3 團隊開發程式撰寫慣例公約
  4. 4 Teamwork Code撰寫基本守則
  5. 5 JavaBean Naming Rules
無規距不成方圓, 有規距自成方圓.(規距不能亂也!)
  • 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