资讯频道 → 非技术
阅读更多

0顶
0踩

非技术

转载新闻 代码是灵魂，注释是心声

2014-11-26 15:58 by 正式编辑 cao345657340 评论(1) 有4739人浏览
编程 工作 情感
在以前一些关于代码注释的文章中，我发现，你不需要的注释才是最好的注释。不要急着批判，请允许我阐述一下。首先代码应该尽量地简洁，尽可能地做到不需要依赖注释就可以理解。只有那些真的没法更易于理解的代码，才需要我们添加注释。



有一本非常经典的书叫《Structure and Interpretation of Computer Programs》（《电脑程序的结构和编译》），最初发表于1985年，在序言中就表明其观点：
引用
程序必须能便于我们阅读，让机器执行只是附带的。

Knuth也在他1984年发表的经典论文《Literate Programming》（《文学编程》）中秉持了类似的观点：

引用
我们应该转变传统的思维，程序不再是告诉计算机做什么的指令，而是向人类描述如何让计算机做事情的文字，编程像写文章一样。

文学编程关注的主要是展现精致的风格。程序员应该像作家一样，认真地选择变量名，并解释每个变量的意思，努力写出易于人脑理解的程序。

如果你写出来的代码，既能被其他程序员理解又能成功编译，那么需要添加注释的地方肯定就不会很多。关于使用注释作为辅助工具，下面就是一个颇具代表意义的例子：

这段代码取自一个已经使用多年、闭源了的系统。

引用
float _x = abs(x - deviceInfo->position.x) / scale;
int directionCode;
if (0 < _x & x != deviceInfo->position.x) {
    if (0 > x - deviceInfo->position.x) {
        directionCode = 0x04 /*left*/;
    } else if (0 < x - deviceInfo->position.x) {
        directionCode = 0x02 /*right*/;
    }
}

上面的代码等同于下面的代码，但是下面的代码可读性更高。

引用
static const int DIRECTIONCODE_RIGHT = 0x02;

static const int DIRECTIONCODE_LEFT = 0x04;

static const int DIRECTIONCODE_NONE = 0x00;

int oldX = deviceInfo->position.x;

int directionCode = (x > oldX) ? DIRECTIONCODE_RIGHT : (x > oldX) ? DIRECTIONCODE_LEFT : DIRECTIONCODE_NONE;

需要注意的是，注释的越多并不意味着代码的理解性更强。当然在本案例中并没有涉及到这一点。上面的注释——如果你注意到的话——使得代码更加显得凌乱不堪。有时候，注释得越精简代码的可读性才越高。特别是在你必须更换使用其他符号名的情况下。

虽然我们能无限次地重构和精简代码以避免写繁冗的注释，但是表述自己的思考过程的方式却是有局限性的。

无论最后你呈现的代码是有多么的简洁和清楚，代码也不可能完全自文档化。但是代码永远也不可能取缔注释的存在。正如Jef Raskin所说：

[代码]无法解释如此写程序以及选择该方法的原因。从[代码]上我们也看不出选择某些替代方法的理由。例如：

引用
/* A binary search turned out to be slower than the Boyer-Moore algorithm for the data sets of interest, thus we have used the more complex, but faster method even though this problem does not at first seem amenable to a string search technique. */

在A开发人员看来完全显而易见的东西，可能在B眼里完全就像雾里看花一样。所以我们在写注释的时候，也要考虑到这一点：

下面这个可能你一清二楚

引用
$string = join('',reverse(split('',$string)));

反转字符串，但是要如何才能插入到

引用
# Reverse the string

Perl文件中呢？

的确，这一点都不难。归根究底，代码只会告诉你程序是如何工作的，但是注释则能说明工作的原因。所以，下次你写代码的时候，不妨在这两个方面给你的同事做个榜样。
  • 大小: 61.7 KB
来自: 码农网
0
顶
0
踩
评论 共 1 条 请登录后发表评论
1 楼 letmedown 2014-11-26 16:59
程序员最好理解相关的业务知识

发表评论

您还没有登录,请您登录后再发表评论

相关推荐

  • 华为程序员写代码十几年没有被拿去“祭天”，靠的是这5条口诀

    好代码长什么模样练好扎实的基本功一行代码引发的惨案“变更防护墙”够不够可靠保持对于新兴技术的好奇心本文来源华为心声社区：http://tinyurl.com/y2568w4s徐宏伟 华为软件专家一天晚上，我和老婆聊天，说部门要我...

  • 大牛——心声

    注释是程序的一个重要组成部分，它可以使你的代码更容易理解，而如果代码已经清楚地表达了你的思想，就不必再加注释了，如果注释和代码不一致，那就更加糟糕。 　8. 韧性和毅力。这也许是"高手"和一般程序员最大的...

  • 真的要做一辈子的程序员吗？来自10年程序员的心声

    在可读性与效率中保持平衡，通常情况下我们优先考虑可读性，但是对于频繁执行的部分，可以牺牲可读性保证效率，但需要书写足够多的注释，注释不要说代码的用途，而要说自己写代码时思考的内容，我就曾经见过有人把一...

  • Flutter 嵌套深、刷新乱？少年，你怕是连Flutter的门槛都没摸到！

    人有读古国文化史者循代而下至于卷末必凄以有所觉如脱春温而入于秋肃勾萌绝朕枯槁在前吾无以名姑谓之萧条而止盖人文之留遗后世者最有力莫如心声古民神思接天然之宫冥契万有与之灵会道其能道爰为诗歌其声度时劫而入...

  • 你不得不读的书籍清单

    你不得不读的书籍清单，岁月如梭，转眼间2015年将要过去，本篇博文也就将告一段落！毕竟年复一年的累加下去，本篇文章可能会导致加载失败（笑，自嘲），约吗？让我们来年再战！

  • Android Studio最全解析

    　22.Ctrl+/和Ctrl+Shift+/可以注释代码 　23.Ctrl+Alt+B可以跳转到抽象方法的实现 　24.Ctrl+O可以选择父类的方法进行重写 　25.Ctrl+Q可以看JavaDoc 　26.Ctrl+Alt+Space是类名自动完成 ...

  • 网吧计费管理系统开发历程与源码分享(武汉理工大学程序设计综合实验课程设计)

    之前我以为编程就是枯燥无味的打几十行代码，但是通过这门课，我发现编程也可以更有趣！其次，这个计费管理系统不错哟！通过这个系统，我们可以实现添加卡，查询卡，激活卡，注销卡，挂失卡，上机，下机，退费，转账...

  • 安心学习，重学前端之（js基础篇（1））

    感觉最近IT圈子有点嗨啊，996.icu大火，也是我们it从业者的心声，活着!=活着。其实无论是在公司，还是回家，技术都融入了我自己的生活吧，只是资本家的操作，不予评论，安心做技术。 话扯远了，言归正传，这个文档，...

  • 我在华为写了13年代码的一些感悟

    本文摘自“心声社区” 华为人，感谢作者辛苦分享。一天晚上，我和老婆聊天，说部门要我写个“大咖谈软件”的文章，老婆斜了我一眼，淡淡地说：“Linus大神21岁就写出了Lin...

  • 高效的敏捷测试第十一课 敏捷测试分析、策略和方法

    有了这样的认知，客户思维又上升了一个台阶，更关注客户的真实愿望，会主动和客户交流，聆听客户的心声，挖掘客户的真实需求。 在实际的业务需求分析中，完全站在用户的角度去看问题，从用户的喜怒哀乐出发，反过来...

  • 2006年度10大技术开发类图书

    其余按首字拼音顺序排列）入围名单（按首字拼音顺序排列）:.NET设计规范Ajax基础教程Ajax实战编程的奥秘 .NET及相关类C#高级编程(第4版)C#入门经典(第3版)C++ Primer中文版(第4版)代码大全(第二版)Effective C++:...

  • Eclipse，到了说再见的时候了——Android Studio最全解析

    　22.Ctrl+/和Ctrl+Shift+/可以注释代码 　23.Ctrl+Alt+B可以跳转到抽象方法的实现 　24.Ctrl+O可以选择父类的方法进行重写 　25.Ctrl+Q可以看JavaDoc 　26.Ctrl+Alt+Space是类名自动完成 　27.快速打开类/文件/符号...

  • 程序员也应该多花时间多读书

    想想beyond中，除了灵魂 黄家驹 ，也就叶世荣让我最为怀念。 真的，第一次感觉到原来人还可以这样 肆意妄为 的活着，然而，这终究不会是我的世界，然而我确实羡慕这样的人生，足够精彩，足够精彩，足够精彩！ ...

  • Android studio安装下载

    　22.Ctrl+/和Ctrl+Shift+/可以注释代码 　23.Ctrl+Alt+B可以跳转到抽象方法的实现 　24.Ctrl+O可以选择父类的方法进行重写 　25.Ctrl+Q可以看JavaDoc 　26.Ctrl+Alt+Space是类名自动完成 ...

  • Java毕设项目：基于spring+mybatis+maven+mysql实现的优选生鲜电商系统【含源码+数据库+毕业论文】

    一、项目简介 本项目是一套基于SSM框架实现的菜匣子优选生鲜电商系统蔬菜水果商城 包含：项目源码、数据库脚本等，该项目附带全部源码可作为毕设使用。 项目都经过严格调试，eclipse或者idea 确保可以运行！ 该系统功能完善、界面美观、操作简单、功能齐全、管理便捷，具有很高的实际应用价值 二、技术实现 jdk版本：1.8 及以上 ide工具：IDEA或者eclipse 数据库: mysql5.7 后端：spring+springmvc+mybatis+maven+mysql 前端：jsp，css，jquery 三、系统功能 系统用户包括有管理员、用户 主要功能如下： 用户登录 用户注册 首页 个人中心 修改密码 个人信息 用户管理 商品分类管理 商品信息管理 商品上架 商品下架 添加库存、减少库存 系统管理 订单管理 商品信息展示 点我收藏 添加到购物车 立即购买 确认下单 支付 余额充值 退款 新闻资讯 我的订单 我的地址 我的收藏等功能 详见 https://flypeppa.blog.csdn.net/article/details/139756831

  • 数字图像取证.pptx

    数字图像取证.pptx

  • Java源码springboot的房屋交易平台的设计与实现-毕业设计论文-期末大作业.zip

    本项目是基于Java语言和Spring Boot框架构建的房屋交易平台的设计与实现，可作为毕业设计论文及期末大作业的素材。项目主要功能涵盖用户注册登录、房源信息发布与浏览、租赁交易管理等。通过该平台，房东能轻松发布房屋信息并随时管理房源状态，用户可以便捷地查找浏览房源并预约看房。平台采用前后端分离架构，后端Spring Boot负责业务逻辑处理与数据管理，其自动配置等特性有助于简化开发流程，前端利用Vue.js构建用户界面，组件的灵活使用使页面交互体验较好。本项目旨在将计算机相关知识应用于实际场景，让学习者通过项目实战深入理解知识，锻炼解决问题的能力。项目为完整毕设源码，先看项目演示，希望对需要的同学有帮助。

  • 2-万能拍照识别2.0 一款多功能拍照识别应用

    万能拍照识物是一款多功能拍照识别应用，可以拍照识别动物、植物、菜肴、车型、二维码和条形码、物品等。支持从手机内存选取图片识别，识别文字后可一键复制，显示识别结果后可一键搜索更多资料。操作方便，识别准确。 【使用方法】：安装软件后，打开相机对准想要识别的对象进行拍照，或者从相册中选择图片进行识别。识别完成后，可以选择复制文字或搜索更多信息。

  • 基于神经音频编解码器的高效语音分离技术研究-Codecformer模型

    内容概要：本文探讨了将语音分离任务嵌入到神经音频编解码器（NAC）的特征空间内的新方法，提出了一种新型模型——Codecformer。该模型在推理时减少了52倍MAC操作次数，同时分离性能与云部署的Sepformer相当。此外，还引入了新的损失函数——Codec SI-SDR，用于指导训练过程。 适合人群：从事音频信号处理和机器学习的研究人员和工程师。 使用场景及目标：①需要高效执行语音分离的边缘计算应用；②降低云计算对音频传输和处理的成本。 其他说明：通过对比不同训练目标的影响以及RVQ层的效果，证明了在压缩编码特征空间内进行语音分离的可行性及其优势。文章还指出了未来可以改进的方向，包括对混合数据预训练NAC和探索Codecformer作为下游任务的第一阶段模型。

Global site tag (gtag.js) - Google Analytics