作業要求-代碼規范

之后涉及編碼的作業要求寫明個人或團隊所采用的代碼規范，同學至少制定並在作業中給出基本的縮進、命名和注釋的規范，並且組內要遵循各自制定和使用的規范。

注意，制定的規范不要過度復雜或生硬套用大企業的標准，以免過度影響開發效率；也不應太過簡略，這樣將難以達到規范編碼的需要。

可以采用現有的規范或自行編寫，希望切實可行，容易觀察和客觀檢驗。代碼不符合規范的，將扣除代碼規范的分數。

例如：

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

---

這里以阿里發布的Java開發手冊v1.4為准，摘取部分作為基本的代碼規范示例。此處僅作示例，請同學們根據自身情況制定合適的編碼規范。

一、命名風格

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 的隨意命名方式。

二、代碼格式

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

三、注釋規約

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/阿里巴巴Java開發手冊終極版v1.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]