代码注释的副作用有哪些

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

公司主营业务:成都网站设计、成都网站建设、移动网站开发等业务。帮助企业客户真正实现互联网宣传,提高企业的竞争能力。创新互联是一支青春激扬、勤奋敬业、活力青春激扬、勤奋敬业、活力澎湃、和谐高效的团队。公司秉承以“开放、自由、严谨、自律”为核心的企业文化,感谢他们对我们的高要求,感谢他们从不同领域给我们带来的挑战,让我们激情的团队有机会用头脑与智慧不断的给客户带来惊喜。创新互联推出凤阳免费做网站回馈大家。

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

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


网页标题:代码注释的副作用有哪些
文章网址:http://scyanting.com/article/ippgsh.html