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

1、Best Practice

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

反例

/**
     * generate signature by code, the algorithm is as follows:
     * 1.sort the http params, if you use java, you can easily use treeMap data structure
     * 2.join the param k-v
     * 3.use hmac-sha1 encrypt the specified string
     *
     * @param params request params
     * @param secret auth secret
     * @return secret sign
     * @throws Exception  exception
     */
    public static String generateSignature(Map<String, Object> params, String secret) throws Exception {
        final StringBuilder paramStr = new StringBuilder();
        final Map<String, Object> sortedMap = new TreeMap<>(params);
        for (Map.Entry<String, Object> entry : sortedMap.entrySet()) {
            paramStr.append(entry.getKey());
            paramStr.append(entry.getValue());
        }

        Mac hmac = Mac.getInstance("HmacSHA1");
        SecretKeySpec sec = new SecretKeySpec(secret.getBytes(), "HmacSHA1");
        hmac.init(sec);
        byte[] digest = hmac.doFinal(paramStr.toString().getBytes());

        return new String(new Hex().encode(digest), "UTF-8");
    }

說明

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

正例

/**
     * generate signature by params and secret, used for computing signature for http request.
     *
     * @param params request params
     * @param secret auth secret
     * @return secret sign
     * @throws Exception  exception
     */
    public static String generateSignature(Map<String, Object> params, String secret) throws Exception {
        final StringBuilder paramStr = new StringBuilder();
        final Map<String, Object> sortedMap = new TreeMap<>(params);
        for (Map.Entry<String, Object> entry : sortedMap.entrySet()) {
            paramStr.append(entry.getKey());
            paramStr.append(entry.getValue());
        }

        Mac hmac = Mac.getInstance("HmacSHA1");
        SecretKeySpec sec = new SecretKeySpec(secret.getBytes(), "HmacSHA1");
        hmac.init(sec);
        byte[] digest = hmac.doFinal(paramStr.toString().getBytes());

        return new String(new Hex().encode(digest), "UTF-8");
    }

總結

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

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

正例

/**
 * <p>
 * Helpers for {@code java.lang.System}.
 * </p>
 * <p>
 * If a system property cannot be read due to security restrictions, the corresponding field in this class will be set
 * to {@code null} and a message will be written to {@code System.err}.
 * </p>
 * <p>
 * #ThreadSafe#
 * </p>
 *
 * @since 1.0
 * @version $Id: SystemUtils.java 1583482 2014-03-31 22:54:57Z niallp $
 */
public class SystemUtils {}

總結

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

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

反例

/**
 *
 * @author yzq
 * @date 2017
 */
public interface KeyPairService {

    PlainResult<KeyPairInfoModel> createKeyPair(KeyPairCreateParam createParam);
}

說明

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

正例