代码注释的副作用有哪些

本篇内容介绍了“代码注释的副作用有哪些”的有关知识，在实际案例的操作过程中，不少人都会遇到这样的困境，接下来就让小编带领大家学习一下如何处理这些情况吧！希望大家仔细阅读，能够学有所成！

代码注释 vs 代码文档

1. 代码注释包含代码文档（类，方法，属性，常量描述）

2. 代码文档必要，非代码文档非必要

代码注释的使用场景

1. 新同学上手，快速把握脉络。

2. 复用方法时存疑，快速查询注释避免方法副作用。

3. 回顾代码实现，还原原始实现意图。

4. 专制不服管教儿童，毁灭技术信仰。（定义模糊，可用于指鹿为马）

代码注释的副作用

1. 好代码 > 烂代码 + 注释（影响代码整洁）

2. 携带历史包袱（历史TODO，历史背景细节） => 不敢删

3. 无标准，无法量化，无法评估（个体差异大，强行推广，易影响开发效率，推行代码注释到不看代码注释）

4. 可能导致团队陷入不思代码结构设计的混沌状态

代码注释示例

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

    /**
     * Tests if the specified object is a key in this table.
     *
     * @param  key possible key
     * @return {@code true} if and only if the specified object
     *         is a key in this table, as determined by the
     *         {@code equals} method; {@code false} otherwise
     * @throws NullPointerException if the specified key is null
     */
    public boolean containsKey(Object key) {
        return get(key) != null;
    }

代码注释的个人建议

1. 控制注释粒度（一般到代码文档级别即可，当你需要细粒度注释时，先考虑这段逻辑是否改抽出来写）

2. 明晰注释作用域（描述一行代码，描述一个Loop）

3. 注释不留包袱（历史背景信息，未处理TODO，保持基线文档级别的代码注释）

4. 作为复杂逻辑的补充解释（中间结果格式示例，为什么捕获异常，为什么不）

5. 理解代码注释的目标，可读，提效（换位思考）

代码注释共识如何达成？

1. 脑暴

2. 试行

3. 阶段回收意见，案例分享（去差异化）

“代码注释的副作用有哪些”的内容就介绍到这里了，感谢大家的阅读。如果想了解更多行业相关的知识可以关注亿速云网站，小编将为大家输出更多高质量的实用文章！