代码中到底应不应当写注释?

 更新时间:2014年10月08日 09:18:01   投稿:hebedich  
注释的确有其用途,但大部分情况下,程序员在滥用注释。我是反对夹杂在代码间的注释的,我认为注释应当从代码中独立出来——通常被称为文档。

当很多前辈教育后辈应当多写注释的时候,当网络上充满了有关程序员从不写注释的段子的时候,这是一个非常有争议的话题。作为一个标题党,容我先修正一下我的观点:我认为如果代码写得足够好,那么大多数注释是多余的,我们应该通过写出更好的代码来代替更多注释。

注释的确有其用途,但大部分情况下,程序员在滥用注释。我是反对夹杂在代码间的注释的,我认为注释应当从代码中独立出来——通常被称为文档。

请看下面一段代码。

复制代码 代码如下:

/* /static/market/checkout.js

2014.7.2 create by orzfly
2014.7.29 update by jysperm: fixbugs

TODO: 这段代码中注释太多了,需要移除一些 -- jysperm
*/

var raw_products = req.query['products'].split(',');

// 商品 ID 的数组
var products = []

// 过滤每个参数
for(var i = 0, i < raw_products.length, i++) {
    if (!raw_products[i])
        return;

    // 前端传来的数据中居然会有空格
    if (!raw_products[i].trim())
        return

    /* 2014.7.22: 现在可以使用非数字 ID 了
    // 略过非数字条目
    if (isNan(raw_products[i].trim().toFixed()))
        return;
    */

    products.push(raw_products[i].trim().toFixed());
}

// 总钱数
var sum = 0;

// 计算每个商品的总钱数
for(var i = 0, i < products.length, i++) {
    // 从数据库中查商品信息
    var data = db.product.byID(products[i]);

    // TODO: 谁来写一下没查到商品的情况

    // 把商品的价格加到总钱数上, a += b 是 a = a + b 的缩写
    sum += data.price;
}

你居然花了一半的时间在读注释上面,这是多么浪费生命的事情,在代码中每加一行注释,都会增加代码的阅读成本——即使阅读者已经了解了注释所要传达的精神;同时也会增加维护成本:修改这段代码的人不得不连同注释一起修改——而且你不能确定他到底会不会这么做。

所以只有当非常必要的情况下,才应该添加注释,而且应当言简意赅。注释不应当解释一段代码在做什么,因为这是每个合格的程序员都应该知道的事情,而是应该解释这段代码为什么要这样做。

由此引出几种明显不应该添加的注释:

本应由版本控制系统记录的信息、对代码的评论,以及不是很重要的 TODO.

代码并不是全部,一个但凡靠谱一点的项目,都应当有自己的版本控制系统,除了记录代码差异之外,还应该有工单和 Issue 的功能。
阅读代码的人通常不需要了解几个程序员之间的恩怨,很多时候也不关心这段代码的历史,这些信息只会把代码拖得越来越长。

废弃的代码

被弃用的代码应该被删掉,这些代码会非常影响阅读,而且它们一般又很长。
在绝大多数情况下,被弃用的代码不会重新派上用场,即使出现了少数情况,你也可以从版本控制系统中找到它们。

对变量和函数名的解释

这种情况下显然你需要一个更恰当的名字,如果这个标识符有一个比较小的作用于,你可以使用一个比较长的名字以便容纳更多信息。

例如上文中的:

products 应改为 products_id
sum 应改为 total_amount
data 应改为 product_record
对语法的解释,以及显而易见的事情

例如上文中的「把商品的价格加到总钱数上, a += b 是 a = a + b 的缩写」,这显然是任何一个人都知道的事情。

也许有人愿意通过写这样的注释来梳理思路:

复制代码 代码如下:

// 过滤参数:
//    去掉 ID 里的空格
//    去掉非数字 ID
// 循环每一个商品:
//    去数据库查记录
//    把商品的价格加到总钱数上

但是当代码写完的时候记得删掉。

对逻辑块的概括

例如上文中的「过滤每个参数」和「计算每个商品的总钱数」,这情况下通常是你没有对逻辑进行抽象,具体表现就是像下面这样:

复制代码 代码如下:

// 首先有 25 行代码去做事情 A
// 然后有 5 行代码去做事情 B
// 这里有 90 行代码去做事情 C
// 最后有 45 行代码去做事情 D

这导致你需要一些注释来分割这四个部分。如果这四个部分都是一个函数调用的话,那么函数名本身就是对逻辑的一种解释,读者可以快速地找到函数 B, 而不必在前 25 行中搜索做事情 B 的五行代码。

综上,我对这段代码的改善意见如下:

复制代码 代码如下:

var filterProductID = function(raw_products_id) {
    result = []

    raw_products_id.forEach(function(product_id) {
        if (product_id and product_id.trim())
            products_id.push(product_id.trim().toFixed());
    });

    return result;
};

var getPriceOfProduct = function(id) {
    var product_record = db.product.byID(products[i]);

    if (product_record)
        return product_record.price;
    else
        return 0;
};

var products_id = filterProductID(req.query['products'].split(','));
var tatol_amount = 0;

products_id.forEach(function(product_id) {
    tatol_amount += getPriceOfProduct(product_id);
});

虽然我在以一段虚构的,刻意编造的代码来佐证我的观点,但我相信在实际的项目中,同样可以通过改善代码来减少注释,而且总体上来讲会节约更多的时间和精力。

相关文章

  • 2018年GitHub账户注册图文教程(github从注册到使用)

    2018年GitHub账户注册图文教程(github从注册到使用)

    Github是最流行的代码库,里面存储着丰富的优秀的开源代码。不仅如此,作为一款免费的代码存储利器也是流的一逼,支持各种编程语言,代码显示效果堪称完美,可以随时随地查看自己记录的笔记
    2018-02-02
  • 安全校验Session验证码并避免绕开验证码攻击

    安全校验Session验证码并避免绕开验证码攻击

    校验验证码的Session是否为空或者校验用户输入的验证码是否合法,构造安全表单的关键就是永远不要相信用户的输入
    2012-01-01
  • Node后端Express框架安装及应用

    Node后端Express框架安装及应用

    Express 是一个简洁而灵活的 node.js Web应用框架, 提供了一系列强大特性帮助你创建各种 Web 应用和丰富的 HTTP 工具,如果你不会jJava or Python等后端,使用 Express可以帮助我们快速地搭建一个完整功能的网站
    2021-08-08
  • gaussdb 200安装 data studio jdbc idea链接保姆级安装步骤

    gaussdb 200安装 data studio jdbc idea链接保姆级安装步骤

    这篇文章主要介绍了gaussdb 200安装 data studio jdbc idea链接保姆级安装步骤,本文通过图文并茂的形式给大家介绍的非常详细,对大家的学习或工作具有一定的参考借鉴价值,需要的朋友可以参考下
    2021-08-08
  • Asp与JS的数组和字符串下标介绍

    Asp与JS的数组和字符串下标介绍

    数组都是从0开始。javascript是arrayname[i],而vbscript是arrayname(i),javascript的字符串还是从0开始,asp的字符串下标从1开始
    2013-03-03
  • 算法系列15天速成 第一天 七大经典排序【上】

    算法系列15天速成 第一天 七大经典排序【上】

    今天是开篇,得要吹一下算法,算法就好比程序开发中的利剑,所到之处,刀起头落
    2013-11-11
  • git push指令常见选项和用法详解

    git push指令常见选项和用法详解

    Git中的git push命令用于将本地仓库的改动推送到远程仓库,是协同开发中的重要工具,在团队合作中,使用git push和git pull可以有效维护项目同步,避免冲突,推送时若遇到冲突需先解决后再进行推送,需要的朋友可以参考下
    2024-09-09
  • 详解Git 的 rebase 命令使用方法

    详解Git 的 rebase 命令使用方法

    这篇文章主要介绍了Git 的 rebase 命令使用方法,接下来,我们使用rebase命令,其命令一般形式为git rebase feature,即表示在 master 分支上执行rebase命令,将 feature 分支的代码合并到 master 分支,本文给大家介绍的非常详细,需要的朋友可以参考下
    2022-05-05
  • 一文详解VSCode安装配置使用(最新版超详细保姆级含插件)

    一文详解VSCode安装配置使用(最新版超详细保姆级含插件)

    安装VScode就很简单了,一路NEXT就可以了,重点是配置使用以及插件推荐,这篇文章主要给大家介绍了关于VSCode安装配置使用的相关资料,本文是最新版超详细保姆级含插件,需要的朋友可以参考下
    2023-05-05
  • IDEA2019.3在Plugins中搜索不到translation的解决

    IDEA2019.3在Plugins中搜索不到translation的解决

    这篇文章主要介绍了IDEA2019.3在Plugins中搜索不到translation的解决,文中通过图文的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧
    2020-06-06

最新评论