翻譯的Equinox Team編碼實踐
注:原文地址見:http://eclipse.org/equinox/documents/coding.php
Equinox包括了相當大量的代碼,Equinox團隊遵循一系列的編碼規范以及編碼實踐來保證代碼的一致性。其中大部分的編碼規范都可以通過Eclipse工具(Formating Setting)來實現,鑒于此,建議可以通過Eclipse的工具來保證大部分編碼規范的實施。
基本原則
u 所有非提交者的貢獻必須是有跡可循的。最簡單的方法就是在包含了patch/貢獻的Bug報告中增加[應用了貢獻補丁]的注釋。
u 所有的類都必須有正確的版權聲明。
u 如果代碼是2003年寫的,那么在版權信息中不要寫成2000—2003這樣的形式。
代碼格式標準
u 使用Equinox代碼格式設定。(導入格式xml文件至eclipse中)
u 設置需要導入的導入包的數字到3(之后的部分用*方式代替)。
u 刪除分組列表里的所有條目來屏蔽導入的分組特性。
u 在提交至CVS前格式化代碼(Ctrl+Shift+F)并且組織導入的包(Ctrl+Shift+O)。
u 不要濫用空行。把代碼組織起來就像在寫文章的時候會把句子組織成段落一樣。
u 每個Equinox項目都必須使用這些設定以確保每個人的代碼設定都一樣。
注釋
u 注釋是一種好習慣。
u API必須編寫JavaDoc。
u 按照Javadoc的指導編寫Javadoc,就象@since作為推薦說明。
u 對于不可見的部分同樣給予注釋,包括方法、變量定義、算法步驟等。
命名
u Class/method/field的命名要能代表其編寫的目的。
u 在命名時注意語義上的作用。不允許以類型來命名,Java本來就是一種強類型的預言,為什么還要在命名上重復類型名呢?舉例來說,setFoo(Foo value)比setFoo(Foo foo)顯得更為有意義。
u 盡量使用全部拼寫,少用縮寫。(就像getProjectValue就比getProjVal好)
u 避免使用”temp”或”index”來對變量命名。(例外的情況同樣存在,比如象在loop循環中使用i ,j 這樣的短命名)
u get/set方法應保留給真正的存取屬性使用。(注:在equinox team執行時也不是完全嚴格的這么執行)
u 避免隨機的單詞前綴,如”a”、”the”,對于命名沒有幫助。
工具的使用(Eclipse)
u 打開所有的編譯提醒開關,如未使用的變量、未使用的包等等。
u 打開javadoc的編譯警告。
菜單:Javadoc->Process Javadoc comments
-Malformed Javadoc comments -> warning
-Report Errors in tags -> true
u 任務的編譯。Equinox Team使用了三種任務(TODO,FIXME和XXX),不要增加自定義的任務編譯項,否則整個Team的人都要改變任務的編譯設定。
u 按字母順序對類中的方法排序。
u 使用有意義的數字對于數據類型的大小進行初始化,不要使用象new HashSet(65)這樣的形式。
u 除非在實現類中必須使用,否則請使用接口定義變量類型以及方法簽名。
u 使用存取方法(get/set)操作存取屬性,不要直接操作其他類中的變量。
u 盡量早的使用if、true的方式來判斷程序是否需要退出,如如果整個方法處于if(!foo){}中,那還不如用if(foo) return;
u 如對于捕獲的異常不進行處理,必須說明原因(如編譯警告等)。
u 如果在拋出異常時直接編寫異常的信息會導致該行非常的長,Equinox Team的通常做法是首先定義好拋出異常的信息。
u 如果返回的值有可能為null,請判斷。
u 使用IPath對路徑進行邏輯處理,而不要使用Strings和concatenation。
u 盡量不要去捕捉Exception,而是去捕捉特定的有意義的異常。(如CoreException這些自定義的)
u 不要把整個方法都放在try{}catch(){}里面,這樣會沒法得到具體的錯誤信息。
u 確保所有的file I/O是做了緩沖處理的。
u 當代碼需要與其他人共享時,確保上傳到CVS的代碼是可編譯的。
國際化
u 按照NLS的原則以及Eclipse的NLS機制。
u 所有顯示給用戶的句子必須以句號結尾。
u 刪除不使用的信息。
posted on 2005-11-18 14:05 BlueDavy 閱讀(1089) 評論(0) 編輯 收藏 所屬分類: Java