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

最佳实践

1. 注释应该声明代码的高层次意图，而非明显的细节

反例

/**
     * 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)，大家都会看代码

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

正例

/**
 * <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 {}

总结

通常每个文件或类都应该有一个全局注释来概述该类的作用

3. 公共api需要添加注释，其它代码谨慎使用注释

反例

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

    PlainResult<KeyPairInfoModel> createKeyPair(KeyPairCreateParam createParam);
}

说明

以上接口提供dubbo rpc服务属于公共api，以二方包的方式提供给调用方，虽然代码简单缺少了接口概要描述及方法注释等基本信息。

正例

/**
 * dubbo service: key pair rpc service api.
 *
 * @author yzq
 * @date 2017/02/22
 */
public interface KeyPairService {

    /**
     * create key pair info.
     *
     * @param createParam key pair create param
     * @return BaseResult
     */
    PlainResult<KeyPairInfoModel> createKeyPair(KeyPairCreateParam createParam);
}

总结

公共api一定要有注释，类文件使用类注释，公共接口方法用方法注释

4. 在注释中用精心挑选的输入输出例子进行说明

正例

/**
     * <p>Checks if CharSequence contains a search character, handling {@code null}.
     * This method uses {@link String#indexOf(int)} if possible.</p>
     *
     * <p>A {@code null} or empty ("") CharSequence will return {@code false}.</p>
     *
     * <pre>
     * StringUtils.contains(null, *)    = false
     * StringUtils.contains("", *)      = false
     * StringUtils.contains("abc", 'a') = true
     * StringUtils.contains("abc", 'z') = false
     * </pre>
     *
     * @param seq  the CharSequence to check, may be null
     * @param searchChar  the character to find
     * @return true if the CharSequence contains the search character,
     *  false if not or {@code null} string input
     * @since 2.0
     * @since 3.0 Changed signature from contains(String, int) to contains(CharSequence, int)
     */
    public static boolean contains(final CharSequence seq, final int searchChar) {
        if (isEmpty(seq)) {
            return false;
        }
        return CharSequenceUtils.indexOf(seq, searchChar, 0) >= 0;
    }

总结

对于公共的方法尤其是通用的工具类方法提供输入输出的例子往往比任何语言都有力

5. 注释一定要描述离它最近的代码

反例

private Map<String, String> buildInstanceDocumentMap(String version, String instanceId) {
        Map<String, String> instanceDocumentMap = Maps.newLinkedHashMap();

        Map<String, String> instanceDocumentMapMetadataPart = metaDataService.getInstanceDocument(instanceId, version,
            instanceDocumentMetaKeys);
        instanceDocumentMap.putAll(instanceDocumentMapMetadataPart);
        //the map must remove the old key for instance type
        instanceDocumentMap.put("instance-type", instanceDocumentMap.get("instance/instance-type"));
        instanceDocumentMap.remove("instance/instance-type");

        return instanceDocumentMap;
    }

说明

该方法有一行代码从map里删除了一个数据，注释放在了put调用之前，而没有直接放在remove之前

正例

private Map<String, String> buildInstanceDocumentMap(String version, String instanceId) {
        Map<String, String> instanceDocumentMap = Maps.newLinkedHashMap();

        Map<String, String> instanceDocumentMapMetadataPart = metaDataService.getInstanceDocument(instanceId, version,
            instanceDocumentMetaKeys);
        instanceDocumentMap.putAll(instanceDocumentMapMetadataPart);
        instanceDocumentMap.put("instance-type", instanceDocumentMap.get("instance/instance-type"));
        //the map must remove the old key for instance type
        instanceDocumentMap.remove("instance/instance-type");

        return instanceDocumentMap;
    }

总结

注释要放在距离其描述代码最近的位置

6. 注释一定要与代码对应

反例

/**
     * 根据hash过后的id生成指定长度的随机字符串, 且长度不能超过16个字符
     * 
     * @param len length of string
     * @param  id id
     * @return String
     */
    public static String randomStringWithId(int len, long id) {
        if (len < 1 || len > 32) {
            throw new UnsupportedOperationException("can't support to generate 1-32 length random string");
        }
        //use default random seed
        StringBuffer sb = new StringBuffer();
        long genid = id;
        for (int i = 0; i < len; i++) {
            long pos = genid%32 ;
            genid = genid>>6;
            sb.append(RANDOM_CHAR[(int) pos]);
        }
        return sb.toString();

    }

说明

注释中说明生成随机字符串的长度不能超过16字符，实际代码已经修改为32个字符，此处注释会产生误导读者的副作用

正例

/**
     * 根据hash过后的id生成指定长度的随机字符串
     * 
     * @param len length of string
     * @param  id id
     * @return String
     */
    public static String randomStringWithId(int len, long id) {
        if (len < 1 || len > 32) {
            throw new UnsupportedOperationException("can't support to generate 1-32 length random string");
        }
        //use default random seed
        StringBuffer sb = new StringBuffer();
        long genid = id;
        for (int i = 0; i < len; i++) {
            long pos = genid%32 ;
            genid = genid>>6;
            sb.append(RANDOM_CHAR[(int) pos]);
        }
        return sb.toString();

    }

总结

• 注释一定要与代码对应，通常代码变化对应的注释也要随之改变
• 若非必要慎用注释，注释同代码一样需要维护更新

7. 一定要给常量加注释

反例

/**
 * define common constants for ebs common component.
 *
 * Author: yzq Date: 16/7/12 Time: 17:44
 */
public final class CommonConstants {

    /**
     * keep singleton
     */
    private CommonConstants() {}

    public static final String BILLING_BID = "26842";

    public static final int BILLING_DOMAIN_INTEGRITY_VALID = 1;

    public static final int BILLING_READYFLAG_START = 0;
}

正例

/**
 * define common constants for ebs common component.
 *
 * Author: yzq Date: 16/7/12 Time: 17:44
 */
public final class CommonConstants {

    /**
     * keep singleton
     */
    private CommonConstants() {}


    /**
     * oms client bid.
     */
    public static final String BILLING_BID = "26842";

    /**
     * oms billing domain integrity true.
     */
    public static final int BILLING_DOMAIN_INTEGRITY_VALID = 1;

    /**
     * oms billing readyflag start.
     */
    public static final int BILLING_READYFLAG_START = 0;
}

总结

• 给每一个常量加一个有效的注释

8. 巧用标记（TODO，FIXME，HACK）

• TODO 有未完成的事项
• FIXME 代码有已知问题待修复
• HACK 表示代码有hack逻辑

示例

public static String randomStringWithId(int len, long id) {
        // TODO: 2018/6/11 需要将len的合法范围抽象
        if (len < 1 || len > 32) {
            throw new UnsupportedOperationException("can't support to generate 1-32 length random string");
        }
        //use default random seed
        StringBuffer sb = new StringBuffer();
        long genid = id;
        for (int i = 0; i < len; i++) {
            long pos = genid%32 ;
            genid = genid>>6;
            sb.append(RANDOM_CHAR[(int) pos]);
        }
        return sb.toString();

    }

配置标记

可以扩展IDE修改标记的配置，比如加入解决人，关联缺陷等信息，以IDEA为例修改入口如下：

image.png

总结

• 巧用TODO、FIXME、HACK等注解标识代码
• 及时处理所有标识代码，忌滥用

9. 适当添加警示注释

正例

private BaseResult putReadyFlag(BillingDataContext context, Integer readyFlag) {
        // warn! oms data format require List<Map<String,String>> and the size of it must be one.
        List<Map<String, String>> dataList = Lists.newArrayListWithExpectedSize(1);
    }

说明

该方法创建了一个大小固定为1且类型为 Map<String,String> 的数组链表，这个用法比较奇怪，需要注释说明原因

总结

代码里偶尔出现一些非常hack的逻辑且修改会引起较高风险，这个时候需要加注释重点说明

10. 注释掉的代码

反例

private Object buildParamMap(Object request) throws Exception {
        if (List.class.isAssignableFrom(request.getClass())) {
            List<Object> input = (List<Object>)request;
            List<Object> result = new ArrayList<Object>();
            for (Object obj : input) {
                result.add(buildParamMap(obj));
            }
            return result;
        }

        Map<String, Object> result = new LinkedHashMap<String, Object>();
        Field[] fields = FieldUtils.getAllFields(request.getClass());
        for (Field field : fields) {
            if (IGNORE_FIELD_LIST.contains(field.getName())) {
                continue;
            }

            String fieldAnnotationName = field.getAnnotation(ProxyParam.class) != null ? field.getAnnotation(
                ProxyParam.class).paramName() : HttpParamUtil.convertParamName(field.getName());

            //Object paramValue = FieldUtils.readField(field, request, true);
            //if (paramValue == null) {
            //    continue;
            //}
            //
            //if (BASIC_TYPE_LIST.contains(field.getGenericType().getTypeName())) {
            //    result.put(fieldAnnotationName, String.valueOf(paramValue));
            //} else {
            //    result.put(fieldAnnotationName, this.buildParamMap(paramValue));
            //}

        }
        return result;
    }

说明

常见套路，为了方便需要的时候重新复用废弃代码，直接注释掉。

正例

同上，删除注释部分代码

总结

不要在代码保留任何注释掉的代码，版本管理软件如Git可以做的事情不要放到代码里

11. 循规蹈矩式注释

反例

/**
 * 类EcsOperateLogDO.java的实现描述：TODO 类实现描述
 * 
 * @author xxx 2012-12-6 上午10:53:21
 */
public class DemoDO implements Serializable {

    private static final long serialVersionUID = -3517141301031994021L;

    /**
     * 主键id
     */
    private Long              id;

    /**
     * 用户uid
     */
    private Long              aliUid;

    /**
     * @return the id
     */
    public Long getId() {
        return id;
    }

    /**
     * @param id the id to set
     */
    public void setId(Long id) {
        this.id = id;
    }

    /**
     * @return the aliUid
     */
    public Long getAliUid() {
        return aliUid;
    }

    /**
     * @param aliUid the aliUid to set
     */
    public void setAliUid(Long aliUid) {
        this.aliUid = aliUid;
    }
}

说明

分析上述代码可以发现两处注释非常别扭和多余：

• 类注释使用了默认模版, 填充了无效信息
• IDE为Getter及Setter方法生成了大量的无效注释

正例

/**
 * Demo model.
 * @author xxx 2012-12-6 上午10:53:21
 */
public class DemoDO implements Serializable {

    private static final long serialVersionUID = -3517141301031994021L;

    /**
     * 主键id
     */
    private Long              id;

    /**
     * 用户uid
     */
    private Long              aliUid;

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public Long getAliUid() {
        return aliUid;
    }

    public void setAliUid(Long aliUid) {
        this.aliUid = aliUid;
    }
}

总结

• 不要保留任何循规蹈矩式注释，比如IDE自动生成的冗余注释
• 不要产生任何该类注释，可以统一配置IDE达到该效果，推荐使用灵狐插件

12. 日志式注释

反例

/** 支持xxx   code by xxx 2015/10/11  */
        String countryCode = param.getCountyCode();
        if(StringUtils.isNotBlank(countryCode) && !"CN".equals(countryCode)){
            imageOrderParam.setCountyCode(param.getCountyCode());
            imageOrderParam.setCurrency(param.getCurrency());
        }

说明

修改已有代码很多人会手动添加注释说明修改日期，修改人及修改说明等信息，这些信息大多是冗余的

正例

代码同上，删除该注释

总结

不要在代码中加入代码的著作信息，版本管理软件可以完成的事情不要做在代码里

“拐杖注释”

反例

/**
     * update config map, if the config map is not exist, create it then put the specified key and value, then return it
     * @param key config key
     * @param value config value
     * @return config map
     */
    public Map<String, String> updateConfigWithSpecifiedKV(final String key, final String value) {
        if (StringUtils.isNotBlank(key) || StringUtils.isNotBlank(value)) {
            return Maps.newHashMap();
        }
        
        Map<String, String> config = queryConfigMap();
        if (MapUtils.isEmpty(config)) {
            return new HashMap<String, String>() {{
                put(key, value);
            }};
        }

        config.put(key, value);
        return config;
    }

说明

示例代码简单实现了更新指定map k-v等功能，如果目标map不存在则使用指定k-v初始化一个map并返回，方法名为 updateConfigWithSpecifiedKV ，为了说明方法的完整意图，注释描述了方法的实现逻辑

正例

/**
     * create or update config map with specified k-v.
     *
     * @param value config value
     * @return config map
     */
    public Map<String, String> createOrUpdateConfigWithSpecifiedKV(final String key, final String value) {
        if (StringUtils.isNotBlank(key) || StringUtils.isNotBlank(value)) {
            return Maps.newHashMap();
        }

        Map<String, String> config = queryConfigMap();
        if (MapUtils.isEmpty(config)) {
            return new HashMap<String, String>() {{
                put(key, value);
            }};
        }

        config.put(key, value);
        return config;
    }

总结

抛弃“拐杖注释”，不要给不好的名字加注释，一个好的名字比好的注释更重要

13. 过度html化的注释

反例

/**
 * used for indicate the field will be used as a http param, the http request methods include as follows:
 * <li>Get</li>
 * <li>Post</li>
 * <li>Connect</li>
 *
 * the proxy param will be parsed, see {@link ProxyParamBuilder}.
 *
 * @author yzq
 * @date 2017/12/08
 */
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface ProxyParam {

    /**
     * the value indicate the proxy app name, such as houyi.
     *
     * @return proxy app name
     */
    String proxyApp() default "houyi";

    /**
     * proxy request mapping http param.
     *
     * @return http param
     */
    String paramName();

    /**
     * the value indicate if the param is required.
     *
     * @return if this param is required
     */
    boolean isRequired() default true;
}

说明

类注释使用了大量的html标签用来描述，实际效果并没有带来收益反而增加阅读难度

正例

/**
 * used for indicate the field will be used as a http param.
 *
 * @author yzq
 * @date 2017/12/08
 */
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface ProxyParam {

    /**
     * the value indicate the proxy app name, such as houyi.
     *
     * @return proxy app name
     */
    String proxyApp() default "houyi";

    /**
     * proxy request mapping http param.
     *
     * @return http param
     */
    String paramName();

    /**
     * the value indicate if the param is required.
     *
     * @return if this param is required
     */
    boolean isRequired() default true;
}

总结

• 普通业务注释谨慎使用html标签，它不会给你带来明显收益，只会徒增阅读难度
• 如果是公共api且用于生成javadoc可以考虑加入必要的html标签，比如链接，锚点等

编程语言注释实践

Java

文件/类注释规范

目前IDE安装 灵狐 后会自动配置IDE的file templates为如下格式：

/**
 * @author ${USER}
 * @date ${YEAR}/${MONTH}/${DAY}
 */

强烈建议使用如上配置，统一、简洁就是最好。如果有特殊需要需要定制类注释可以参考下图：

image.png

方法注释

/**  
     * xxx
     * 
     * @param 
     * @param 
     * @return 
     * @throws 
     */

IDE提供了统一的方法注释模版，无需手动配置，好的方法注释应该包括以下内容：

• 方法的描述，重点描述该方法用来做什么，有必要可以加一个输入输出的例子
• 参数描述
• 返回值描述
• 异常描述

举个例子：

/**
     * Converts a <code>byte[]</code> to a String using the specified character encoding.
     *
     * @param bytes
     *            the byte array to read from
     * @param charsetName
     *            the encoding to use, if null then use the platform default
     * @return a new String
     * @throws UnsupportedEncodingException
     *             If the named charset is not supported
     * @throws NullPointerException
     *             if the input is null
     * @deprecated use {@link StringUtils#toEncodedString(byte[], Charset)} instead of String constants in your code
     * @since 3.1
     */
    @Deprecated
    public static String toString(final byte[] bytes, final String charsetName) throws UnsupportedEncodingException {
        return charsetName != null ? new String(bytes, charsetName) : new String(bytes, Charset.defaultCharset());
    }

块注释与行注释

• 单行代码注释使用行注释 //
• 多行代码注释使用块注释 /* */

Python

文件注释

• 重点描述文件的作用及使用方式

#!/usr/bin/python
# -*- coding: UTF-8 -*-

"""
bazaar script collection.

init_resource_entry, used for init bazaar resource such as vpc, vsw, sg, proxy ecs and so on.

user manual:
1. modify ecs.conf config your key, secret, and region.
2. run bazaar_tools.py script, this process will last a few minutes，then it will generate a init.sql file.
3. use idb4 submit your ddl changes.

"""

类注释

"""
    ecs sdk client, used for xxx.

    Attributes:
        client:
        access_key: 
        access_secret:
        region:
    """

• 类应该在其定义下有一个用于描述该类的文档字符串
• 类公共属性应该加以描述

函数注释

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
    """Fetches rows from a Bigtable.

    Retrieves rows pertaining to the given keys from the Table instance
    represented by big_table.  Silly things may happen if
    other_silly_variable is not None.

    Args:
        big_table: An open Bigtable Table instance.
        keys: A sequence of strings representing the key of each table row
            to fetch.
        other_silly_variable: Another optional variable, that has a much
            longer name than the other args, and which does nothing.

    Returns:
        A dict mapping keys to the corresponding table row data
        fetched. Each row is represented as a tuple of strings. For
        example:

        {'Serak': ('Rigel VII', 'Preparer'),
         'Zim': ('Irk', 'Invader'),
         'Lrrr': ('Omicron Persei 8', 'Emperor')}

        If a key from the keys argument is missing from the dictionary,
        then that row was not found in the table.

    Raises:
        IOError: An error occurred accessing the bigtable.Table object.
    """
    pass

• Args:列出每个参数的名字, 并在名字后使用一个冒号和一个空格, 分隔对该参数的描述.如果描述太长超过了单行80字符,使用2或者4个空格的悬挂缩进(与文件其他部分保持一致). 描述应该包括所需的类型和含义. 如果一个函数接受*foo(可变长度参数列表)或者**bar (任意关键字参数), 应该详细列出*foo和**bar.
• Returns: 描述返回值的类型和语义. 如果函数返回None, 这一部分可以省略
• Raises:列出与接口有关的所有异常

多行注释与行尾注释

# We use a weighted dictionary search to find out where i is in
# the array.  We extrapolate position based on the largest num
# in the array and the array size and then do binary search to
# get the exact number.

if i & (i-1) == 0:        # true iff i is a power of 2

• 复杂操作多行注释描述
• 比较晦涩的代码使用行尾注释

Golang

行注释

常用注释风格

包注释

/**/ 通常用于包注释, 作为一个整体提供此包的对应信息，每个包都应该包含一个doc.go用于描述其信息。

/*
    ecs OpenApi demo，use aliyun ecs sdk manage ecs, this package will provide you function list as follows:

    DescribeInstances, query your account ecs.
    CreateInstance, create a ecs vm with specified params.
 */
package ecsproxy

JavaScript

常用/**/与//，用法基本同Java。

Shell

只支持 # ，每个文件都包含一个顶层注释，用于阐述版权及概要信息。

其它

待完善

小结

本文先总结了注释在编程中的最佳实践场景并举例进行了说明，然后就不同编程语言提供了一些注释模版及规范相关的实践tips。关于注释我个人的认知是：注释即代码，注释即文档，写好注释一个工程师必备的素质之一，在整洁代码前提下，更少的注释是更高的追求。关于注释的实践暂时写到这里，后面会持续完善，也欢迎大家提供好的tips，文中代码大多出自于日常业务项目，也有部分摘自开源库，若有不妥之处敬请指正。