做業要求-代碼規範

以後涉及編碼的做業要求寫明我的或團隊所採用的代碼規範，同窗至少制定並在做業中給出基本的縮進、命名和註釋的規範，而且組內要遵循各自制定和使用的規範。

注意，制定的規範不要過分複雜或生硬套用大企業的標準，以避免過分影響開發效率；也不該太過簡略，這樣將難以達到規範編碼的須要。

能夠採用現有的規範或自行編寫，但願切實可行，容易觀察和客觀檢驗。代碼不符合規範的，將扣除代碼規範的分數。

例如：

• 每一個函數不超過5行，對於初學者是不切實際的;
• 大括號匹配縱列對齊，是切實可行的;
• 變量名易讀，是不易檢驗的；
• 變量名必須是名詞短語，遵循匈牙利命名法，是易於檢驗的。

---

這裏以阿里發佈的Java開發手冊v1.4爲準，摘取部分做爲基本的代碼規範示例。此處僅做示例，請同窗們根據自身狀況制定合適的編碼規範。

1、命名風格

1. 【強制】代碼中的命名均不能如下劃線或美圓符號開始，也不能如下劃線或美圓符號結束。
   • 反例：_name / __name / $name / name_ / name$ / name__
2. 【強制】代碼中的命名嚴禁使用拼音與英文混合的方式，更不容許直接使用中文的方式。
   • 說明：正確的英文拼寫和語法可讓閱讀者易於理解，避免歧義。注意，即便純拼音命名方式也要避免採用。國際通用的名稱，可視同英文。
   • 反例：DaZhePromotion [打折] / getPingfenByName() [評分] / int 某變量 = 3
     
3. 【強制】類名使用 UpperCamelCase 風格，但如下情形例外：DO / BO / DTO / VO / AO / PO / UID 等。
   • 正例：MarcoPolo / UserDO / XmlService / TcpUdpDeal / TaPromotion
   • 反例：macroPolo / UserDo / XMLService / TCPUDPDeal / TAPromotion
4. 【強制】方法名、參數名、成員變量、局部變量都統一使用 lowerCamelCase 風格，必須聽從駝峯形式。
   • 正例： localValue / getHttpMessage() / inputUserId
5. 【強制】常量命名所有大寫，單詞間用下劃線隔開，力求語義表達完整清楚，不要嫌名字長。
   • 正例：MAX_STOCK_COUNT
   • 反例：MAX_COUNT
6. 【強制】抽象類命名使用 Abstract 或 Base 開頭；異常類命名使用 Exception 結尾；測試類 命名以它要測試的類的名稱開始，以 Test 結尾。
7. 【強制】包名統一使用小寫，點分隔符之間有且僅有一個天然語義的英語單詞。包名統一使用單數形式，可是類名若是有複數含義，類名可使用複數形式。
   • 正例：應用工具類包名爲 com.alibaba.ai.core.util、類名爲 MessageUtils（此規則參考 spring 的框架結構）
8. 【強制】杜絕徹底不規範的縮寫，避免望文不知義。
   • 反例：AbstractClass「縮寫」命名成AbsClass；condition「縮寫」命名成 condi，此類隨 意縮寫嚴重下降了代碼的可閱讀性。
9. 【推薦】爲了達到代碼自解釋的目標，任何自定義編程元素在命名時，使用盡可能完整的單詞組合來表達其意。
   • 正例：在 JDK 中，表達原子更新的類名爲：AtomicReferenceFieldUpdater。
   • 反例：變量 int a 的隨意命名方式。

2、代碼格式

1. 【強制】大括號的使用約定。若是是大括號內爲空，則簡潔地寫成{}便可，不須要換行；若是是非空代碼塊則：
   • 左大括號前不換行。
   • 左大括號後換行。
   • 右大括號前換行。
   • 右大括號後還有 else 等代碼則不換行；表示終止的右大括號後必須換行。
2. 【強制】if/for/while/switch/do 等保留字與括號之間都必須加空格。
3. 【強制】採用 4 個空格縮進，禁止使用 tab 字符。

3、註釋規約

1. 【強制】類、類屬性、類方法的註釋必須使用 Javadoc 規範，使用/**內容*/格式，不得使用 // xxx 方式。
   • 說明：在 IDE 編輯窗口中，Javadoc 方式會提示相關注釋，生成 Javadoc 能夠正確輸出相應註釋；在 IDE 中，工程調用方法時，不進入方法便可懸浮提示方法、參數、返回值的意義，提升閱讀效率。
2. 【強制】全部的抽象方法（包括接口中的方法）必需要用 Javadoc 註釋、除了返回值、參數、異常說明外，還必須指出該方法作什麼事情，實現什麼功能。
   • 說明：對子類的實現要求，或者調用注意事項，請一併說明。
3. 【強制】全部的類都必須添加建立者和建立日期。
   
4. 【強制】方法內部單行註釋，在被註釋語句上方另起一行，使用//註釋。方法內部多行註釋 使用/* */註釋，注意與代碼對齊。
5. 【強制】全部的枚舉類型字段必需要有註釋，說明每一個數據項的用途。
6. 【推薦】與其「半吊子」英文來註釋，不如用中文註釋把問題說清楚。專有名詞與關鍵字保持英文原文便可。
   • 反例：「TCP鏈接超時」解釋成「傳輸控制協議鏈接超時」，理解反而費腦筋。
7. 【推薦】代碼修改的同時，註釋也要進行相應的修改，尤爲是參數、返回值、異常、核心邏輯等的修改。
   • 說明：代碼與註釋更新不一樣步，就像路網與導航軟件更新不一樣步同樣，若是導航軟件嚴重滯後，就失去了導航的意義。
8. 【參考】謹慎註釋掉代碼。在上方詳細說明，而不是簡單地註釋掉。若是無用，則刪除。
   • 說明：代碼被註釋掉有兩種可能性：
     • 後續會恢復此段代碼邏輯。
     • 永久不用。
   • 前者若是沒有備註信息，難以知曉註釋動機。後者建議直接刪掉（代碼倉庫保存了歷史代碼）。

---

參考資料：

Coding conventions
[https://en.wikipedia.org/wiki/Coding_conventions]

Programming style
[https://en.wikipedia.org/wiki/Programming_style]

Google Style Guide
[https://github.com/google/styleguide]

阿里巴巴Java開發手冊
[https://files-cdn.cnblogs.com/files/han-1034683568/%E9%98%BF%E9%87%8C%E5%B7%B4%E5%B7%B4Java%E5%BC%80%E5%8F%91%E6%89%8B%E5%86%8C%E7%BB%88%E6%9E%81%E7%89%88v1.3.0.pdf]

.NET框架設計準則
[https://docs.microsoft.com/zh-cn/dotnet/standard/design-guidelines/]

團隊項目開發"編碼規範"系列文章
[http://www.cnblogs.com/huyong/archive/2011/03/18/1988423.html]

C#編碼規範
[http://www.cnblogs.com/wulinfeng/archive/2012/08/31/2664720.html]

咱們的終極編碼規範
[http://www.cnblogs.com/leotsai/p/our-ultimate-coding-standards.html]

本身總結的C#編碼規範
[http://www.cnblogs.com/luzhihua55/p/CodeConvention7.html]