xx專案程式碼規範與專案質量
從以往各種的經驗來看,一個優秀的產品或專案,經過千錘百煉,成為一個內涵豐富的寶藏:文件、程式碼、設計、bug的fix和各種思想的火花,都沉澱下來,變成了很多人長期的資產和營養。在這個過程中,專案的質量是長期穩定的。但是一個一般的專案,由於各種因素,開始就質量一般,後來又各種曲折,最終專案質量會從開始的一般水平,很快的下降,收斂到一個非常低得水準。在這個過程中,文件和設計開始殘缺,程式碼開始腐朽,散發著我們常說的bad smell的味道。那麼如何防止這個變壞的過程呢?一是專案一開始就要按照一個簡單高效的方式實施一些規範:程式碼風格、命名、註釋等等,約束概念和形式上的一致性;二是制定較高的質量目標:
程式碼風格
-- 親,一個不合適的ctrl+f會變成merge程式碼的噩夢,請每次格式化的時候,考慮下你用的是不是跟大家一致的模板。
-- 程式碼應該是簡潔的,清晰的,可讀性強的,高效的
模板保證新建的類和方法的註釋風格一致,format格式一致(按120字元每行)。
合理的縮排和空行,便於閱讀程式碼。
提供格式模板,請在eclipse中使用:
詳見上面連結wiki文件的附件,其中codetemplate.xml用於eclipse的java-code style-code template,
命名標準規範
-- 統一各種層次物件的命名,一方面是使得團隊多人的程式碼更一致,更一方面更是我們自己概念理解的統一。
專案
統一使用ieo-xxx方式命名project,比如ieo-web,ieo-biz,ieo-common等等。
包、類
包名必須小寫,儘量一個單詞或縮寫。
包名應該和所在專案名一致,與包下的類的作用一致。
實現類所在的包應該是介面或抽象類的包名字尾.impl。
類名的每個單詞首字母必須大寫。
類名必須能直接表達本類的作用。
類名的字尾必須表達出其所在分層,比如Screen,AO
方法
方法名稱首字母必須小寫,後續每個單詞首字母大小。
方法名必須能直接表達方法體的作用。
引數名稱必須是有意義的。
增刪改查的方法使用create, delete, update, find開頭。
區域性變數
區域性變數名稱必須是有意義的,禁止使用user1,user2,user3,a,b,c命名。
常量
靜態常量需要加上final。
公用的常量必須放在常量類中
非公用的常量可以放置在使用的類中,宣告為private
可以列舉的常量集合必須使用常量或列舉類
常量名稱必須是有意義的
常量必須全部大寫,並使用下劃線連線不同的單詞
使用很少的字面量,在不影響閱讀的情況下可以不使用常量宣告,直接寫在程式碼中
配置檔案
spring相關的配置檔案,按層次或功能劃分不同的配置檔案
spring所有的bean,一般按照類名或介面名首字母小寫命名
spring配置檔案預設使用byname的autowire
sqlmap必須使用xxxx-sqlmap結尾
VM檔案
檔名必須與內容在意義上一致。
檔名首字母小寫,後續單詞首字母大寫。
vm檔案中的變數引用需要注意使用!判斷空。
名詞參照表
對於行業相關術語的和常用命名的字首,請在這裡查詢,如果找不到請新增到這裡並周知大家:
xxxxxxx
註釋規範
-- 如果說程式碼本身說明了在做什麼,註釋則是說明了為什麼要這麼做。複雜的程式碼沒有註釋,過幾天你自己都看不懂了。
介面、類和public的方法必須要有註釋,請參考風格模板,或者eclipse裡在方法和類上shift、alt+J
待定的功能、review的問題、修復的bug,請使用TODO,REVIEW,FIXME標記。
bug修復,問題排查時修改的關鍵程式碼,請加上註釋,說明修改人,修改時間,問題分析和採取的措施,如果說明較多在wiki上,請加上鍊接。
日誌標準規範
-- 日誌是用來排查問題的,你今天寫什麼註定你以後用什麼。所有寫操作必須有日誌所有日誌必須有唯一標識(比如update一條資料,必須記錄id)
必須說清楚本操作是做什麼的,影響了什麼,結果如何所有與第三方互動資料必須輸出原始報文(比如xml或soap)
日誌必須使用enabled判斷:log.isDebugEnabled(){ log.debug(...); }
單元測試要求
-- 單元測試的目的是持續的保證程式碼方法層次的邏輯是對的,一直都是對的,改了也是改對了的。
最小粒度方法級的邏輯測試
覆蓋所有邏輯分支判斷和邊界條件
不依賴具體的某些絕對條件,比如寫死的日期
不能catch異常不處理
test case不得在執行時有依賴關係
test case的包名類名與被測類保持一致
test case的方法建議一般使用中文
能mock的物件儘量mock,比如對外部的依賴,本test case不關注的manager-
核心模組如biz、dal、core,要求必須70%以上。
其他模組如web等,建議30%以上。
SVN要求
-- svn是可靠的,當然前提是使用svn的人必須是可靠的。
提交時必須輸入說明修改目的的備註,比如修改日期格式化錯誤問題,解決bug id:123456
分支名稱必須帶日期版本號加上分支說明,比如廉航的分支:v051216_20120308_Lianhang
其他要求
整個專案使用GBK編碼
設計文件評審前必須發出並收集反饋意見,評審需要針對意見
模組程式碼完成和大範圍修改(非小bug fix),必須code review
參考列表
xxxxx