一、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,以二方包的方式提供给调用方,虽然代码简单缺少了接口概要描述及方法注释等基本信息。