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

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

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

请看下面一段代码。

代码如下:

/* /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);
});

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

赞 (0)

相关推荐

  • Javascript 倒计时源代码.(时.分.秒) 详细注释版

    随便写写!闲着无聊!代码如有bug之处欢迎阁下强力拍砖! JS CODE 复制代码 代码如下: <script type="text/javascript" language="javascript"> //总时间,已分为单位 var time = 100; //小时 var h = parseInt(time / 60) > 0 ? parseInt(time / 60) : 0; //分 var m = time % 60; //秒 var s

  • 网页中返回顶部代码(多种方法)另附注释说明

    网页中返回顶部代码(多种方法)另附注释说明

    下面就说下简单的返回顶部效果的代码实现,附注释说明. 1. 最简单的静态返回顶部,点击直接跳转页面顶部,常见于固定放置在页面底部返回顶部功能 方法一:用命名锚点击返回到顶部预设的id为top的元素 复制代码 代码如下: <a href="#top" target="_self">返回顶部</a> 方法二:操作scrooll函数用来控制滚动条的位置(第一个参数是水平位置,第二个参数是垂直位置) 复制代码 代码如下: <a href=&qu

  • PHP压缩html网页代码(清除空格,换行符,制表符,注释标记)

    PHP压缩html网页代码 (清除空格,换行符,制表符,注释标记). 有个不错的方法就是压缩HTML,压缩html 其实就是:清除换行符,清除制表符,去掉注释标记 .它所起到的作用不可小视. 现提供PHP 压缩HTML函数.请大家不妨试试看,感觉还不错吧. 不废话了,直接上代码: 复制代码 代码如下: <?php /** * 压缩html : 清除换行符,清除制表符,去掉注释标记 * @param $string * @return 压缩后的$string * */ function compr

  • asp.net画曲线图(折线图)代码 详细注释

    复制代码 代码如下: using System; using System.Collections; using System.Configuration; using System.Data; using System.Web; using System.Web.Security; using System.Web.UI; using System.Web.UI.HtmlControls; using System.Web.UI.WebControls; using System.Web.UI

  • FCKeditor 源代码分析附中文注释

    这几天都在研究FCKeditor的源代码 (FCKeditor就是网络中应用比较广泛的网页编辑器)  这里需要感谢nileaderblog的辛苦翻译. 几乎搜遍了Internet,似乎对于fckconfig.js这个文件讲解的很多,但对于fckeditor.js这个FCK的核心类文件的资料几乎为0. 所以,花了整整一天的时间,以挤牙膏的方式,对fckeditor.js这个fck核心类文件作了自己力所能及的注释,供同样学习fck的网友一个参考. 鉴于笔者水平有限,在此,请广大高手指出我的注释中不妥

  • jQuery 表格隔行变色代码[修正注释版]

    复制代码 代码如下: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv=&qu

  • JavaScript 事件监听实例代码[兼容IE,firefox] 含注释

    JavaScript事件监听完整实例(含注释) var oEventUtil = new Object(); oEventUtil.AddEventHandler = function(oTarget,sEventType,fnHandler) { //IE和FF的兼容性处理 //如果是FF if(oTarget.addEventListener){ oTarget.addEventListener(sEventType,fnHandler,false); } //如果是IE else if(o

  • HTML代码中标签的全部属性 中文注释说明

    例:写一段图片HTML代码 <img src="http://localhost/phpwind6/zx/6.jpg" id="imgs" lang="en-us" alt="测试"> 该标签为img的代码中已可以看出已含有了四个属性,包括src id lang alt,加上本身的img标签有5个属性. 那么该img标签在正常的情况下倒底还含有多个属性?(包含对象),我现在为大家一一列出来(以上面那句代码为例,并附

  • 代码中到底应不应当写注释？

    当很多前辈教育后辈应当多写注释的时候,当网络上充满了有关程序员从不写注释的段子的时候,这是一个非常有争议的话题.作为一个标题党,容我先修正一下我的观点:我认为如果代码写得足够好,那么大多数注释是多余的,我们应该通过写出更好的代码来代替更多注释. 注释的确有其用途,但大部分情况下,程序员在滥用注释.我是反对夹杂在代码间的注释的,我认为注释应当从代码中独立出来--通常被称为文档. 请看下面一段代码. 复制代码 代码如下: /* /static/market/checkout.js 2014.7.2

  • Python 中写注释的方法

    在写 Python 代码的时候,一个很好的编码实践就是使得你的代码简洁,易懂.组织代码,设置变量,以及给函数有意义的名字,都是几个不错的方法. 另外一个提高代码可读性的方式就是使用注释.一个注释就是可以用来解释代码的一段人类可读的解释或者一个注解.例如,如果你写了一个复杂的正则表达式,你可以添加一个注释,描述代码做了什么. 在你的 Python 代码中添加注释,在将来你阅读你的代码时,可以节省很多的时间和努力.比如说,你想修改一段你在几个月前或者几年前写的脚本.很可能你不记得为什么你写了一些比较

  • IDEA插件之快速删除Java代码中的注释

    IDEA插件之快速删除Java代码中的注释

    背景 有时,我们需要删除Java源代码中的注释.目前有不少方法,比如: 实现状态机.该方式较为通用,适用于多种语言(取决于状态机支持的注释符号). 正则匹配.该方式容易误判,尤其是容易误删字符串. 利用第三方库.该方式局限性较强,比如不同语言可能有不同的第三方库. 本文针对Java语言,介绍一种利用第三方库的方式,可以方便快速地移除代码中的注释. 原理 这个第三方库叫做JavaParser.它可以分析Java源码,并生成语法分析树(AST),其中注释也属于AST中的节点. 因此核心思路即为: J

  • Python 中如何写注释

    在写 Python 代码的时候,一个很好的编码实践就是使得你的代码简洁,易懂.组织代码,设置变量,以及给函数有意义的名字,都是几个不错的方法. 另外一个提高代码可读性的方式就是使用注释.一个注释就是可以用来解释代码的一段人类可读的解释或者一个注解.例如,如果你写了一个复杂的正则表达式,你可以添加一个注释,描述代码做了什么. 在你的 Python 代码中添加注释,在将来你阅读你的代码时,可以节省很多的时间和努力.比如说,你想修改一段你在几个月前或者几年前写的脚本.很可能你不记得为什么你写了一些比较

  • 使用正则去除php代码中的注释方法

    使用正则去除php代码中的注释方法

    测试代码 文件:a.PHP <?php /** * 加法计算 * 测试 */ // 设定$a的值 $a = 10; // 设定$b的值 $b = 5; // 加法 $c = $a + $b; # 输出结果 echo $c; 文件:test.php echo "源码:<br />"; show_source('./a.php'); echo "<hr />去除注释后:<br />"; highlight_string(remo

  • Python代码中引用已经写好的模块、方法的两种方式

    Python代码中引用已经写好的模块、方法的两种方式

    平时写的一些 Python 的代码,需要在其他模块里面复用.最粗狂的方法就是直接 copy 过去. 但这种方式太麻烦,copy 一堆代码,导致代码量也很多.copy 的也不爽. 下面就介绍两种方式,可以简洁明了地调用自己在其他模块写的代码. 个人推荐第二种方式. 方式一: 手动使用 sys 调用自己写的 Python 模块.方法 我的代码存在 E:\\PycharmProjects\\111 目录下.需要调用的代码是 mypy 下 my007.py 里的 funA() 方法. my007.py

  • 如何在js代码中消灭for循环实例详解

    前言 这篇文章基于我在公司内部分享会整理而成.欢迎探讨补充. 补充一:看来很多人没看完文章就评论了.我在文章末尾说了,是不写 for 循环,不是不用 for 循环.简单陈述不写 for 循环的理由:for 循环易读性差,而且鼓励写指令式代码和执行副作用.更多参考这篇文章 补充二:回应大家的一些反对意见.本来准备专门写文章回应的,但是没时间,就简短回复,直接扔链接了. 1.for 循环性能最好.回应:微观层面的代码性能优化,不是你应该关注的.我在文章中演示了,对百万级数据的操作,reduce 只比

  • 详解如何在JS代码中消灭for循环

    Edit: 在我入职第三家公司的第一天,看到代码库里面一堆的 for 循环,内心有些崩溃,于是做了一次技术分享,展示怎样在代码中避免 for 循环.这篇文章是那次分享的总结.本文并不完美,其中递归的部分其实不应该在目前的生产环境中使用.但是我依然坚持认为 JS 引擎应该支持尾调优化,写尾递归和写循环性能没差别. 一,用好 filter,map,和其它 ES6 新增的高阶遍历函数 问题一: 将数组中的 falsy 值去除 const arrContainsEmptyVal = [3, 4, 5,

  • SpringBoot中到底该如何解决跨域问题

    SpringBoot中到底该如何解决跨域问题

    目录 前言 1.跨域访问报错 2.同源定义 3.跨域问题如何解决? 4.CORS原理 5.SpringMVC中如何解决跨域问题? 6.方案1:方法或者类上标注@CrossOrigin注解 7.方案2:全局配置的方式 8.方案3:拦截器的方式CorsFilter 9.案例代码 9.1.案例完整代码 9.2.接口代码:CorsController 9.3.静态页面:cors.html 9.4.将chat21-cores模块发布到tomcat 9.5.运行静态页面cors.html 9.6.点击第1个

随机推荐