代码整洁之道（二）优雅注释之道

一、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 params, String secret) throws Exception { final StringBuilder paramStr = new StringBuilder(); final Map sortedMap = new TreeMap<>(params); for (Map.Entry 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 params, String secret) throws Exception { final StringBuilder paramStr = new StringBuilder(); final Map sortedMap = new TreeMap<>(params); for (Map.Entry 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)，大家都会看代码

在文件/类级别使用全局注释来解释所有部分如何工作