代码注释的副作用有哪些

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

代码注释 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. 阶段回收意见，案例分享（去差异化）

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