《码处高效：Java开发手册》之代码风格
流水淡，碧天長，鴻雁成行。編碼風格，簡捷清爽，反引無限風光。
??在美劇《硅谷》中有這樣一個經典鏡頭，主人公 Richard 與同為開發工程師的女友鬧分手，理由是兩人對縮進方式有著截然不同的編程習慣，互相鄙視對方的代碼風格。Richard 認為＂ one tab saves four spaces ”，縮進使用 Tab 鍵操作更快，更節省存 儲空間，而女友堅持使用空格縮進，連續四次敲擊空格的聲音，把 Richard 折磨到幾近崩潰，認為這是種精神折磨。 Richard 覺得難以相處，吵完架下樓梯時，不小心摔倒了 還淡定地說，"I just tried to go down the stairs four steps at a time ” （這只是表達我的立場而已）。Tab 鍵和空恪鍵的爭議在現實編程中確實存在。除此之外，在其他代碼風格上，也存在不同的處理方式，往往是誰也說服不了誰，都站在自身“完全正確”的立場上，試圖說服對方。這在團隊開發效率上，往往是一個巨大的內耗，無休止的爭論與最后的收益是成反比的。所以我們認為一致性很重要，就像交通規則一樣，我國規定靠右行駛，有些國家則規定靠左行駛，并沒有絕對的優劣之分，但是在同一個國家或地區內必須要有統一的標準。代碼風格也是如此，無論選擇哪一種處理方式，都需要部分人犧牲小我，成就大我，切實提升團隊的研發效能。
??代碼風格并不影響程序運行，沒有潛在的故障風險，通常與數據結構、邏輯表達無關，是指不可見字符的展示方式、代碼元素的命名方式和代碼注釋風格等。比如，大括號是否換行、縮進方式、常量與變量的命名方式、注釋是否統一放置在代碼上方等。代碼風格的主要訴求是清爽統一、便于閱讀和維護。統一的代碼風格可以讓開發工程師們沒有嚴重的代碼心理壁壘，每個人都可以輕松地閱讀并快速理解代碼邏輯，便于高效協作，逐步形成團隊的代碼“味道”。
命名規約
??代碼元素包括類、方法、參數、常量、變量等程序中的各種要素。合適的命名，可以體現出元素的特征、職責 ，以及元素之間的差異性和協同性。為了統一代碼風格，元素的命名要遵守以下約定。
命名符合本語言特性
??當前主流的編程語言有 50 種左右，分為兩大陣營—面向對象與面向過程，但是按變量定義和賦值的要求，分為強類型語言和弱類型語言。每種語言都有自己的獨特命名風格，有些語言在定義時提倡以前綴來區分局部變量、全局變量、控件類型。比如 Ii_count 表示 local int 局部整型變量， dw_report 表示 data window 用于展示報表數據的控件。有些語言規定以下畫線為前綴來進行命名。這些語言的命名風格，自成一派，也無可厚非，但是在同種語言中，如果使用多種語言的命名風格 就會引起其他開發工程師的反感。比如，在 Java 中，所有代碼元素的命名均不能以下畫線或美元符號開始或結束。
命名體現代碼元素特征
? ??命名上可體現出代碼元素的特征，僅從名字上即可知道代碼元素的屬性是什么，有利于快速理清代碼脈絡。面向對象代碼元素的命名形式分為兩大類，即首字母大寫的 UpperCamelCase 和首字母小寫的 lowerCamelCase ，前者俗稱大駝峰，后者俗稱小駝峰。類名采用大駝峰形式，一般為名詞，例如 Object、StringBuffer、 FileInputStream 等。 方法名采用小駝峰形式，一般為動詞，與參數組成動賓結構，例如Object的wait()、StringBuffer的append(String)、FileInputStream的read() 等。變量包括參數、成員變量、局部變量等，也采用小駝峰形式。常量的命名方式比較特殊，字母全部大寫，單詞之間用下畫線連接。常量和變量是最基本的代碼元素，就像血液中的紅細胞一樣無處不在。合理的命名有利于保障代碼機體的清爽、健康。
? ??在命名時若能體現出元素的特征，則有助于快速識別命名對象的作用，有助于快速理解程序邏輯。我們推薦在 Java 命名時，以下列方式體現元素特征：
- 包名統一使用小寫，點分隔符之間有且僅有一個自然語義的英語單詞。包名統一使用單數形式，但是類名如果有復數含義，則可以使用復數形式。
- 抽象類命名使用 Abstract或Base 開頭，異常類命名使用 Exception 結尾；測試類命名以它要測試的類名開始，以Test 結尾。
- 類型與中括號緊挨相連來定義數組。
- 枚舉類名帶上 Enum 后綴，枚舉成員名稱需要全大寫，單詞間用下畫線隔開。
命名最好望文知義
? ??望文知義是在不需要額外解釋的情況下，僅從名稱上就能夠理解某個詞旬的確切含義。在代碼元素命名時做到望文知義，從而減少注釋內容，達到自解釋的目的。在實踐中，望文知義的難度是最大的，就好像給孩子起名一樣需要反復斟酌。文不對題的命名方式，肯定會加大理解成本，更大的罪過是把程序員引導到一個錯誤的理解方向上。某些不規范的縮寫會導致理解成本增加。比如 condition 縮寫成 condi 類似隨意的縮寫會嚴重降低代碼的可理解性。再比如，以單個字母命名的變量，在上下文理解時 會帶來很大的困擾。本書中的所有示例代碼都比較精筒，沒有具體業務含義。重點在于闡述示例背后的編程思維，所以采用單字母的簡潔命名方式，在實際業務代碼中請勿模仿。
? ??主流的編程語言基本上以英語為基礎，此處望文知義的“文”指的是英文。隨著開源社區的發展與繁榮，各國程序員踴躍參與開源項目的共建，國際交流與合作越來越頻繁，英語能力已經成為程序員必備的基礎技能之一。雖然有人認為命名方式應該符合本國語言習慣，拼音這種命名方式，應該是被允許的，但是在國際化項目或開源項目中，對于非漢語國家的開發工程師而言，拼音這種命名方式的可讀性幾乎為零。即使在漢語系家，拼音也存在地區差異。中英文混合的方式，更不應該出現。比如在某業務代碼中，曾經出現過DaZePromotion ，猜了很久才被命名者告知是打折促銷的類。最讓人無法容忍的是拼音“首字母”簡寫的命名方式，即使發揮極致的想象力，也很難猜出具體的含義，比如 PfmxBuilder 名稱意思是評分模型的創建工廠類！這些命名方式，極大增加了程序的理解成本。所以，正確的英文拼寫和語法可以讓閱讀者易于理解，避免歧義。 alibaba、taobao、hangzhou 等國際通用的名稱，可視同英文。某些復合語義的情況下，盡量使用完整的單詞組合來達到望文知義的目的 比如 KeyboardShortcutsHandler、AtomicReferenceFieldUpdater。
? ??命名要符合語言特性、體現元素特征。命名做到望文知義、自解釋是每個開發工程師的基本素質之一。我們在思量更好的代碼元素命名的同時，也要敢于修改已有的、不合理的命名方式。
? ??在所有代碼元素中，常量和變量最為常見，優雅地定義與使用好它們，是開發工程師的基本功之一。
常量
? ??什么是常量？常量是在作用域內保持不變的值， 一般用 final 關鍵字進行修飾，根據作用域區分，分為全局常量、類內常量、局部常量。全局常量是指類的公開靜態屬性 使用 public static final 修飾；類內常量是私有靜態屬性，使用 private static final 修飾，局部常量分為方法常量和參數常量，前者是在方法或代碼塊內定義的常量，后者是在定義形式參數時 增加 final 表示此參數值不能被修改。全局常量和類內常量是最主要的常量表現形式，它們的命名方式比較特殊，采用字母全部大寫、單詞之間加下畫線的方式。而局部常量采用小駝峰形式即可。示例代碼如下：
public class Constant { public static final String GLOBAL CONSTANT = "shared in global";private static final String CLASS CONSTANT = "shared in class";public void f(String a) { final String methodConstant = "shared in method";}public void g( final int b) {// 編譯出錯，不允許對常量參數進行重新賦值b = 3;} }? ?? 常量在代碼中具有穿透性，使用甚廣。如果沒有一個恰當的命名，就會給代碼閱讀帶來沉重的負擔，甚至影響對主干邏輯的理解。首當其沖的問題就是到處使用魔法值。魔法值即“共識層面”上的常量，直接以具體的數值或者字符出現在代碼中。這些不知所云的魔法值極大地影響了代碼的可讀性和可維護性。下面先來看一段實際業務代碼。
public void getOnlinePackageCourse(Long packageId, Long userId) { if (packageId == 3) { logger.error("線下課程，無法在線觀看");return;}// 其它邏輯處理PackageCourse online = packageService.getByTeacherId(userId); if (online.getPackageId() == 2) { logger.error("未審核課程");return;}// 其他邏將處理 }? ??以上示例代碼中，信手拈來的2和3分別表示未審核課程和線下課程，僅僅是兩個數字，似乎很容易記憶。但事實上除2和3兩種狀態外，還有1、4、5分別代表新建、審核未通過、審核通過。在團隊規模較小時，口口相傳，倒也勉強能夠記住這五個數字的含義，早期還有零星的注釋，駕輕就熟的情況下，連注釋也省了。現實是殘酷的，團隊迅速擴大后，課程狀態個數也在逐步增加，新來的開發工程師在上線新功能模塊時，把“審核通過”和“未審核課程”對應的數字搞反了，使得課程展示錯誤，導致用戶大量投訴。隨著應用變得越來越復雜，這些魔法值幾乎成了整個后臺服務代碼中的夢魔。團隊架構師終于下定決心進行系統重構，把這些魔法值以合適的命名方式定義成全局常量。使用 Enum 枚舉類來定義課程類型，示例代碼如下：
public enum CourseTypeEnurn { /*** 允許官方和講師創建和運營*/ VIDEO_COURSE(l, "錄插課程"),/*** 只允許官方創建和運營，初始化必須設置合理的報名人數上限*/LIVE_COURSE(2, "直播課程"）,/*** 只允許官方創建和運營*/OFFLINE_COURSE(3，"線下課程");private int seq; private String desc ; CourseTypeEnurn (int seq, String desc) { this.seq = seq; this. desc = desc ; }public int getSeq() {return seq;}public String getDesc() { return desc;} }? ??上述示例代碼把課程類型分成三種：錄播課程、直播課程、線下課程。枚舉類型幾乎是固定不變的全局常量，使用頻率高、范圍廣，所以枚舉常量都需要添加清晰的注釋，比如業務相關信息或注意事項等。再把課程狀態分為新課程、未審核課程、審核通過、審核未通過、已刪除五種狀態。考慮到后續課程狀態還會再追加，并且狀態沒有擴展信息，所以用不能實例化的抽象類的全局常量來表示課程狀態，示例代碼如
下：
public abstract class BaseCourseState { public static final int NEW_COURSE = 1; public static final int UNAUTHED_COURSE = 2;public static final int PASSED_COURSE = 3; public static final int NOT_PASSED_COURSE = 4; public static final int DELETED_COURSE = 5; }使用重構后的常量修改原有的魔法值，對比一下代碼的可讀性
public void getOnlinePackageCourse(Long packageId, Long userId) { if (packageId == CourseTypeEnum.OFFLINE_COURSE.getSeq()) { logger.error("線下課程，無法在線觀看");return;}// 其它邏輯處理VideoCourse course = packageService.getByTeacherId(userId); if (course.getState() == BaseCourseState.UNAUTHED_COURSE) { logger.error("未審核課程");return;}// 其他邏將處理 }? ??我們認為，系統成長到某個階段后，重構是種必然選擇。優秀的架構設計不是去阻止未來切重構的可能性，畢竟技術枝、業務方向和規模都在不斷變化，而是盡可能讓重構來得晚一些，重構幅度小一些。即使類內常量和局部常量當前只使用一次，也需要賦予一個有意義的名稱，目的有兩個：第一、望文知義，方便理解 第二、后期多次使用時能夠保證值出同源。因此，無論如何都不允許任何魔法值直接出現在代碼中，避免魔法值隨意使用導致取值不一致，特別是對于字符串常量來說，應避免沒有預先定義，就直接使用魔法值。所謂常 在河邊走，哪有不濕鞋，在反復的復制與粘貼后，難免會出現問題，警示代碼如下：
String key = "Id#taobao_" + tradeId; cache.put(key, value);? ??上述代碼是保存信息到緩存中的方法，即使用魔法值組裝 Key。這就導致各個調用方到處復制和粘貼字符串 Id#taobao_ 這樣似乎很合理。但某一天，某個粗心的程序員把Id#taobao_ 復制成為Id#taobao，少了下畫線。這個錯誤在測試過程中，并不容易被發現 因為沒有命中緩存，會自動訪問數據庫。但在大促時，數據庫壓力急劇上升，進而發現緩存全部失效，導致連接占滿，查詢變慢。小處不小，再次說明魔法值害人害己。
? ??某些公認的字面常量是不需要預先定義的，如 for( int i=0; … ）這里的0是可以直接使用的。true和 false也可以直接使用，但是如果具備了特殊的含義，就必須定義出有意義的常量名稱，比如在 TreeMap 源碼中，表示紅黑樹節點顏色的 true 和 false 就被定義成為類內常量，以方便理解∶
private static final boolean RED = false; private static final boolean BLACK = true;? ??常量命名應該全部大寫，單詞間用下畫線隔開，力求語義表達完整清楚，不要嫌名字長，比如，把最大庫存數量命名為 MAX_STOCK_COUNT，把緩存失效時間命名為 CACHE_EXPIRED TIME。
變量
? ??什么是變量從廣義來說，在程序中變量是一切通過分配內存并賦值的量，分為不可變量（常量）和可變變量。從狹義來說，變量僅指在程序運行過程中可以改變其值的量，包括成員變量和局部可變變量等。
? ???一般情況下，變量的命名需要滿足小駝峰格式，命名體現業務含義即可。存在一種特殊情況，在定義類成員變量時，特別是在 POJO類中，針對布爾類型的變量，命名不要加 is 前綴，否則部分框架解析會引起序列化錯誤。例如，定義標識是否刪除的成員變量為 Boolean isDeleted，它的 getter 方法也是 isDeleted()，框架在反向解析的時候，"誤以為"對應的屬性名稱是 deleted，導致獲取不到屬性，進而拋出異常。但是在數據庫建表中，推薦表達是與否的值采用 is_xxx 的命名方式，針對此種情況，需要在<resultMap>中設置，將數據表中的 is_xxx 字段映射到 POJO類中的屬性Xxx。
代碼展示風格
縮進、空格與空行
??縮進、空格與空行造就了代碼的層次性和規律性，有助于直觀、快速、準確地理解業務邏輯。沒有縮進、空格和空行的代碼可讀性極差。如下反例所示∶
table=newTab; if (oldTab!=null){ for(int j=0;j<oldCap;++j){if((e=oldTab[j])!=null){ oldTab[j]=null; if (e.next==null) newTab[e.hash&(newCap-1)]=e;else if(e instanceof TreeNode) if(loTail==null)loHead=e;else oTail.next=e;modCount++; if((tab=table)!=null&&size>=0){ for(int i=0;i<tab.length;++i)tab[i]=null; // 其他代碼 }縮進
??縮進表示層次對應關系。使用 Tab 鍵縮進還是空格縮進長期以來備受爭議，形成兩大陣營。每當在分享會現場調研縮進方式選擇的時候，參與度幾乎都是100%，通常支持空格的人數多于支持Tab 鍵的人數。這時候 Tab 鍵方一般都會提出∶"空格不是有2、4、8個之分嗎?不如讓空格方繼續投票一下，我們Tab 鍵方還是非常團結一致的"。某報告對40萬個開源代碼庫進行了調研，發現近75%的代碼文件使用了空格進行縮進。對于團隊協作來說，一致性風格很重要。我們推薦采用4個空格縮進，禁止使用Tab 鍵。
? ??由于不同編輯器對 Tab 的解析不一致，因此視覺體驗會有差異，而空格在編輯器之間是兼容的。2個空格縮進的層次區分度不明顯，超過4個空格的縮進方式又留白過多，且大多數IDE 默認為4個空格縮進，所以我們采用4個空格的縮進方式。對習慣用 Tab 鍵的工程師來說，唯一的福音是很多IDE 工具提供了Tab 鍵與空格之間的快速轉換設置。IDEA 設置 Tab 鍵為4個空格時，請勿勾選 Use tab character;而在Eclipse 中，必須勾選 Insert spaces for tabs。
空格
??空格用于分隔不同的編程元素。空格可以讓運算符、數值、注釋、參數等各種編程元素之間錯落有致，方便快速定位。空格的使用有如下約定∶
（1）任何二目、三目運算符的左右兩邊都必須加一個空格。
（2）注釋的雙斜線與注釋內容之間有且僅有一個空格。
（3）方法參數在定義和傳入時，多個參數逗號后邊必須加空格。
（4）沒有必要增加若干空格使變量的賦值等號與上一行對應位置的等號對齊。
（5）如果是大括號內為空，則簡潔地寫成{}即可，大括號中間無須換行和空格。
（6）左右小括號與括號內部的相鄰字符之間不要出現空格。
（7）左大括號前需要加空格。
? ??例如，有些工程師習慣在多行賦值語句中對齊等號，如果增加了一條較長的賦值語句，工程師需要更新之前所有的語句對齊格式，這種做法無疑提高了開發成本。此外，雖然不推薦空大括號的代碼出現，但可能會存在干某些測試代碼或者流程語句中，我們推薦空大括號中間無須換行和空格。詳細的示例代碼如下，重點看注釋內容∶
public class SpaceCodeStyle {// 沒有必要增加若干空格使變量的賦值等號與上一行對應位置的等號對齊private static Integer one = 1;private static Long two = 2L;private static Float three = 3F;private static StringBuilder sb = new StringBuilder("code style:");//縮進 4 個空格（注意∶本代碼中的任何注釋在雙斜線與注釋內容之間有且僅有一個空格）public static void main (String[] args)(//繼續縮進4個空格try {// 任何二目運算符的左右必須有一個空格int count = 0;// 三目運算符的左右兩邊都必須有一個空格boolean condition =(count == 0)? true : false;// 關鍵詞if與左側小括號之間必須有一個室格// 左括號內的字母c與左括號、字母n與右括號都不需要空格// 右括號與左大括號前加室格且不換行，左大括號后必須換行if (condition) {System.out.println ("world");// else 的前后都必須加空格// 右大括號前換行，右大括號后有 else時，不用換行} else {System.out.println ("ok");//在右大括號后直接結束，則必須換行}//如果是大括號內為空，則簡潔地寫成{}即可，大括號中間無須換行和空格} catch (Exception e){}// 在每個實參逗號之后必須有一個空格String result = getString(one, two, three, sb);System.out.println (result);}//方法之間，通過空行進行隔斷。在方法定義中，每個形參之后必須有一空格private static String getString(Integer one, Long two, Float three, StringBuilder sb){// 任何二目運算符的左右必須有一個空格，包括賦值運算符，加號運算符等Float temp = one + two + three;sb.append (temp);return sb.toString();} }空行
??空行用來分隔功能相似、邏輯內聚、意思相近的代碼片段，使得程序布局更加清晰。在瀏覽代碼時，空行可以起到自然停頓的作用，提升閱讀代碼的體驗。哪些地方需要空行呢?在方法定義之后、屬性定義與方法之間、不同邏輯、不同語義、不同業務的代碼之間都需要通過空行來分隔。
換行與高度
??代碼中需要限定每行的字符個數，以便適配顯示器的寬度，以及方便CodeReview時進行 diff 比對。對于無節制的行數字符，需要不斷地拉取左右滾動條或者鍵盤移動光標，那是多么差的體驗。因此，約定單行字符數不超過120個，超出則需要換行，換行時遵循如下原則∶
（1）第二行相對第一行縮進4個空格，從第三行開始，不再繼續縮進，參考示例。
（2）運算符與下文一起換行。
（3）方法調用的點符號與下文一起換行。
（4）方法調用中的多個參數需要換行時，在逗號后換行。
（5）在括號前不要換行。
StringBuffer sb = new StringBuffer(); // 超過120個字符的情況下，換行縮進 4個空格，并且方法前的點號一起換行 sb.append ("ma").append("chu")....append ("gao")... .append ("xiao")... .append("yealh");方法行數限制
? ??水平方向上對字符數有限制，那么垂直方向上呢?對于類的長度，只要類功能內聚，不做強制要求。但方法是執行單位，也是閱讀代碼邏輯的最高粒度模塊。龐大的方法容易引起閱讀疲勞，讓人抓不住重點。代碼邏輯要分主次、個性和共性。不要把不同層次的邏輯寫在一個大方法體里，應該將次要邏輯抽取為獨立方法，將共性邏輯抽取成為共性方法（比如參數校驗、權限判斷等），便于復用和維護，使主干代碼邏輯更加清晰。
? ??高內聚、低耦合是程序員最熟悉的口號。如何內聚和解耦，其實方法的行數限制就引發了這些維度的思考。把相關的功能強內聚，把弱相關的功能拆解開來，重新抽象、重新封裝。在拆分方法的過程中，通常會糾結對參數的處理，因為拆分的各個方法之間需要通過參數才能傳遞數據。有這種糾結的前提是方法需要傳入大量的參數，事實上這是另外一個話題。限制參數列表過長的方式有很多，比如包裝成類、隱式傳遞或放在集合中等。
? ??綜上所述，約定單個方法的總行數不超過80行。詳細的判定標準如下，除注釋之外，方法簽名、左右大括號、方法內代碼、空行、回車及任何不可見字符的總行數不超過80 行。為什么是80 行?心理學認為人對事物的印象通常不能超過3這個魔法數，三屏是人類短期記憶的極限，而80 行在一般顯示器上是兩屏半的代碼量。另外，通過對阿里代碼抽樣調查顯示，只有不到5% 的方法才會超過 80行，而這些方法通常都有明顯的優化空間。
? ?? 最后有人說，80行的硬性要求會讓程序員在寫代碼時刻意將多個變量定義在一行，或者if后不寫大括號，或者catch 代碼后使用空語句{}結束。每個公司都有一些強制的代碼風格，肯定有些是大家的代碼素養決定的，少數人偏偏冒天下之大不韙，被這個群體淘汰也是遲早的事情。
控制語句
??控制語句是底層機器碼跳轉指令的實現。方法內部的跳轉控制主要由條件判斷語句和循環語句實現。跳轉能力使程序能夠處理復雜邏輯，具備像人一樣的判斷能力和記憶回溯能力。條件判斷主要由 if、switch、三目運算符組成。循環嚴格意義上也是一種跳轉，主要由 for、while、do-while 組成。
控制語句是最容易出現 Bug 的地方，所以特別需要代碼風格的約束，而不是天馬行空地亂跳。控制語句必須遵循如下約定∶
（1）在if、else、for、while、do-while等語句中必須使用大括號。即使只有一行代碼，也需要加上大括號.
（2）在條件表達式中不允許有賦值操作，也不允許在判斷表達式中出現復雜的邏輯組合。有些控制語句的表達式邏輯相當復雜，與、或、取反混合運算甚至穿插了賦值操作，理解成本非常高，甚至會產生誤解。要解決這個問題，有一個非常簡單的辦法∶將復雜的邏輯運算賦值給一個具有業務含義的布爾變量。例如∶
// 邏輯判斷中使用復雜的邏輯判斷，不易于理解 if((file.open(fileName,"w")!= null) && (...) || !(...)){ } 言 //將復雜的邏輯運算賦值給一個易于理解的布爾變量，方便閱讀代碼 final boolean existed =(file.open(fileName,"w")!= null)&& (...) || !(...); if (existed) {... }（3） 多層嵌套不能超過3層。多層嵌套在哪里都不受歡迎，是因為條件判斷和分支邏輯數量呈指數關系。如果非得使用多層嵌套，請使用狀態設計模式。對于超過3層的if-else 的邏輯判斷代碼，可以使用衛語句、策略模式、狀態模式等來實現，其中衛語句示例如下：
public void today(){if(isBusy()){System.out.println("change time.");return;}if(isFree()){System.out.println("go to travel.");return;}System.out.println("stay at home to learn Easy Coding.");return; }（4）避免采用取反邏輯運算符。取反邏輯不利于快速理解，并且取反邏輯寫法必然存在對應的正向邏輯寫法。比如使用if（x<628）表達x小于628，而不是使用if（!（x >=628))。
代碼注釋
注釋三要素
??注釋是一個看起來簡單，容易被忽視，但是作用又不容小覷的話題。好的注釋能起到指路明燈、撥云見日、警示等作用，具體包括∶能夠準確反映設計思想和代碼邏輯;能夠描述業務含義，使其他工程師能迅速了解背景知識。與代碼不同，注釋沒有語法的限制，完全取決于編寫者的能力和發揮，但這并不意味著注釋可以天馬行空。書寫注釋要滿足優雅注釋三要素。
Nothing is strange
? ??完全沒有注釋的大段代碼對于閱讀者來說形同天書。注釋是給自己看的，即使離寫完代碼很長時間，也能清晰地理解當時的思路;注釋也是給維護者看的，使其能夠快速理解代碼邏輯。
? ??相信大多數人閱讀JDK 源碼時都十分吃力，比如并發控制、集合算法等，這些天才級的程序基本上沒有任何注釋。JDK的代碼穩定、高效壓倒一切，不會朝編夕改。但是業務代碼需要被不斷地維護更新，沒有注釋的代碼給人一種陌生感。世界上最遙遠的距離是，我和要修改的代碼間缺少一段注釋。因此，我們提倡要寫注釋，然后才是把注釋寫得精簡。
Less is more
? ??從代碼可讀性及維護成本方面來講，代碼中的注釋一定是精華中的精華。首先，真正好的代碼是自解釋的，準確的變量命名加上合理的代碼邏輯，無須過多的文字說明就足以讓其他工程師理解代碼的功能。如果代碼需要大量的注釋來說明解釋，那么工程師應該思考是否可以優化代碼表現力。
? ??其次，泛濫的注釋不但不能幫助工程師理解代碼，而且會影響代碼的可讀性，甚至會增加程序的維護成本。如下示例代碼是濫用注釋的樣例，方法名 put，加上兩個有意義的變量名elephant和fridge，已經明確表達了代碼功能，完全不需要額外的注釋。在遇到修改代碼邏輯時，注釋泛濫會帶來災難性的負擔。
// put elephant into fxidge put (elephant, fridge);Advance with the times
? ??與時俱進的重要性對于開發工程師來說是不言而喻的。就像道路狀況與導航軟件一樣，如果導航軟件嚴重滯后，就失去了導航的意義。同樣，針對一段有注釋的代碼，如果程序員修改了代碼邏輯，但是沒有修改注釋，就會導致注釋無法跟隨代碼前進的腳步，誤導后續開發者。因此，任何對代碼的修改，都應該同時修改注釋。
注釋格式
注釋格式主要分為兩種∶ 一種是 Javadoc 規范，另一種是簡單注釋。
? ??類、類屬性和類方法的注釋必須遵循Javadoc規范，使用文檔注釋（/***/）的格式。按 Javadoc 規范編寫的注釋，可以生成規范的 JavaAPI 文檔，為外部用戶提供非常有效的文檔支持。而且在使用IDE 工具編碼時，IDE 會自動提示所用到的類、方法等注釋，提高了編碼的效率。
? ??這里要特別強調對枚舉的注釋是必需的。有人覺得枚舉通常帶了String name 屬性，已經簡要地說明了這個枚舉屬性值的意思，此時注釋是多余的。其實不然，因為∶
? （1）枚舉實在太特殊了。它的代碼極為穩定。如果它的定義和使用出現錯誤，通常影響較大。
? （2）注釋的內容不僅限于解釋屬性值的含義，還可以包括注意事項、業務邏輯。如果在原有枚舉類上新增或修改一個屬性值，還需要加上創建和修改時間，讓使用者零成本地知道這個枚舉類的所有意圖。
? （3）枚舉類的刪除或者修改都存在很大的風險。不可直接刪除過時屬性，需要標注為過時，同時注釋說明過時的邏輯考慮和業務背景。
? ??包括單行注釋和多行注釋。特別強調此類注釋不允許寫在代碼后方，必須寫在代碼上方，這是為了避免注釋的參差不齊，導致代碼版式混亂。雙畫線注釋往往使用在方法內部，此時的注釋是提供給程序開發者、維護者和關注方法細節的調用者查看的。因此，注釋的作用更應該是畫龍點睛的，通常添加在非常必要的地方，例如復雜算法或需要警示的特殊業務場景等。
說明：本文內容參考《碼出高效：Java開發手冊》第三章 代碼風格，有興趣的讀者可以看書的原文。
總結
以上是生活随笔為你收集整理的《码处高效：Java开发手册》之代码风格的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 【黄啊码】微信朋友圈的几分钟/几小时前如
- 下一篇： vuex 中出现[vuex] modul