代碼整潔之道（二）優雅註釋之道

1、Best Practice

註釋應該聲明代碼的高層次意圖，而非明顯的細節

反例

說明

上文方法用於根據參數生成簽名，註釋中詳細描述了簽名算法的實現步驟，這其實就是過分描述代碼明顯細節

正例

總結

1. 註釋必定是表達代碼以外的東西，代碼能夠包含的內容，註釋中必定不要出現
2. 若是有必要註釋，請註釋意圖（why），而不要去註釋實現（how)，你們都會看代碼

在文件/類級別使用全局註釋來解釋全部部分如何工做

正例

總結

一般每一個文件或類都應該有一個全局註釋來概述該類的做用

公共api須要添加註釋，其它代碼謹慎使用註釋

反例

說明

以上接口提供dubbo rpc服務屬於公共api，以二方包的方式提供給調用方，雖然代碼簡單缺乏了接口概要描述及方法註釋等基本信息。

正例

總結

公共api必定要有註釋，類文件使用類註釋，公共接口方法用方法註釋

在註釋中用精心挑選的輸入輸出例子進行說明

正例

總結

對於公共的方法尤爲是通用的工具類方法提供輸入輸出的例子每每比任何語言都有力

註釋必定要描述離它最近的代碼

反例

說明

該方法有一行代碼從map裏刪除了一個數據，註釋放在了put調用以前，而沒有直接放在remove以前

正例

總結

註釋要放在距離其描述代碼最近的位置

註釋必定要與代碼對應

反例

說明

註釋中說明生成隨機字符串的長度不能超過16字符，實際代碼已經修改成32個字符，此處註釋會產生誤導讀者的反作用

正例

總結

1. 註釋必定要與代碼對應，一般代碼變化對應的註釋也要隨之改變
2. 若非必要慎用註釋，註釋同代碼同樣須要維護更新

必定要給常量加註釋

反例

正例

總結

給每個常量加一個有效的註釋

巧用標記（TODO，FIXME，HACK）

1. TODO 有未完成的事項
2. FIXME 代碼有已知問題待修復
3. HACK 表示代碼有hack邏輯

示例

配置標記

能夠擴展IDE修改標記的配置，好比加入解決人，關聯缺陷等信息，以IDEA爲例修改入口以下：

總結

1. 巧用TODO、FIXME、HACK等註解標識代碼
2. 及時處理全部標識代碼，忌濫用

適當添加警示註釋

正例

說明

該方法建立了一個大小固定爲1且類型爲Map的數組鏈表，這個用法比較奇怪，須要註釋說明緣由

總結

代碼裏偶爾出現一些很是hack的邏輯且修改會引發較高風險，這個時候須要加註釋重點說明

註釋掉的代碼

反例

說明

常見套路，爲了方便須要的時候從新複用廢棄代碼，直接註釋掉。

正例

同上，刪除註釋部分代碼

總結

不要在代碼保留任何註釋掉的代碼，版本管理軟件如Git能夠作的事情不要放到代碼裏

循規蹈矩式註釋

反例

說明

分析上述代碼能夠發現兩處註釋很是彆扭和多餘：

1. 類註釋使用了默認模版, 填充了無效信息
2. IDE爲Getter及Setter方法生成了大量的無效註釋

正例

總結

1. 不要保留任何循規蹈矩式註釋，好比IDE自動生成的冗餘註釋
2. 不要產生任何該類註釋，能夠統一配置IDE達到該效果，推薦使用靈狐插件

日誌式註釋

反例

說明

修改已有代碼不少人會手動添加註釋說明修改日期，修改人及修改說明等信息，這些信息大可能是冗餘的

正例

代碼同上，刪除該註釋

總結

不要在代碼中加入代碼的著做信息，版本管理能夠完成的事情不要作在代碼裏

「柺杖註釋」

反例

說明

示例代碼簡單實現了更新指定map k-v等功能，若是目標map不存在則使用指定k-v初始化一個map並返回，方法名爲 updateConfigWithSpecifiedKV ，爲了說明方法的完整意圖，註釋描述了方法的實現邏輯

正例

總結

拋棄「柺杖註釋」，不要給很差的名字加註釋，一個好的名字比好的註釋更重要

過分html化的註釋

反例

說明

類註釋使用了大量的html標籤用來描述，實際效果並無帶來收益反而增長閱讀難度

正例

總結

1. 普通業務註釋謹慎使用html標籤，它不會給你帶來明顯收益，只會徒增閱讀難度
2. 若是是公共api且用於生成javadoc能夠考慮加入必要的html標籤，好比連接，錨點等

2、編程語言註釋實踐

Java

文件/類註釋規範

目前IDE安裝 靈狐 後會自動配置IDE的file templates爲以下格式：

強烈建議使用如上配置，統1、簡潔就是最好。__若是有特殊須要須要定製類註釋能夠參考下圖：

方法註釋

IDE提供了統一的方法註釋模版，無需手動配置，好的方法註釋應該包括如下內容：

1. 方法的描述，重點描述該方法用來作什麼，有必要能夠加一個輸入輸出的例子
2. 參數描述
3. 返回值描述
4. 異常描述

舉個例子：

塊註釋與行註釋

1. 單行代碼註釋使用行註釋 //
2. 多行代碼註釋使用塊註釋 / /

Python

文件註釋

重點描述文件的做用及使用方式

類註釋

1. 類應該在其定義下有一個用於描述該類的文檔字符串
2. 類公共屬性應該加以描述

函數註釋

1. Args:列出每一個參數的名字, 並在名字後使用一個冒號和一個空格, 分隔對該參數的描述.若是描述太長超過了單行80字符,使用2或者4個空格的懸掛縮進(與文件其餘部分保持一致). 描述應該包括所需的類型和含義. 若是一個函數接受foo(可變長度參數列表)或者bar (任意關鍵字參數), 應該詳細列出foo和bar.
2. Returns: 描述返回值的類型和語義. 若是函數返回None, 這一部分能夠省略
3. Raises:列出與接口有關的全部異常

多行註釋與行尾註釋

1. 複雜操做多行註釋描述
2. 比較晦澀的代碼使用行尾註釋

Golang

行註釋

經常使用註釋風格

包註釋

/**/ 一般用於包註釋, 做爲一個總體提供此包的對應信息，每一個包都應該包含一個doc.go用於描述其信息。

JavaScript

經常使用/**/與//，用法基本同Java。

Shell

只支持 # ，每一個文件都包含一個頂層註釋，用於闡述版權及概要信息。

其它

待完善

小結

本文先總結了註釋在編程中的最佳實踐場景並舉例進行了說明，而後就不一樣編程語言提供了一些註釋模版及規範相關的實踐tips。關於註釋我我的的認知是：註釋即代碼，註釋即文檔，寫好註釋一個工程師必備的素質之一，在整潔代碼前提下，更少的註釋是跟高的追求。關於註釋的實踐暫時寫到這裏，後面會持續完善，也歡迎你們提供好的tips，文中代碼大多出自於平常業務項目，也有部分摘自開源庫，如有不妥之處敬請指正。

本文做者：竹澗

閱讀原文

本文爲雲棲社區原創內容，未經容許不得轉載。