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

0顶
0踩

非技术

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

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



有一本非常经典的书叫《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计算器源码.zip

    java毕业设计源码，可供参考

  • FRP Manager-V1.19.2

    Windows下的FRP图形化客户端，对应FRP版本0.61.1,需要64位操作系统

  • 基于优化EKF的PMSM无位置传感器矢量控制研究_崔鹏龙.pdf

    基于优化EKF的PMSM无位置传感器矢量控制研究_崔鹏龙.pdf

  • 旧物置换网站(基于springboot,mysql,java).zip

    旧物置换网站的开发过程中，采用B / S架构，主要使用Java技术进行开发，结合最新流行的springboot框架。中间件服务器是Tomcat服务器，使用Mysql数据库和Eclipse开发 环境。该旧物置换网站包括管理员、用户、卖家。其主要功能包括管理员：首页、个人中心、用户管理、卖家管理、旧物类型管理、旧物信息管理、置换交易管理、系统管理等，卖家后台：首页、个人中心、旧物类型管理、旧物信息管理、置换交易管理。前台首页；首页、旧物信息、网站公告、个人中心、后台管理等，用户后台：首页、个人中心、旧物信息管理、置换交易管理、用户可根据关键字进行信息的查找自己心仪的信息等。 （1）用户功能需求 用户进入前台系统可以查看首页、旧物信息、网站公告、个人中心、后台管理等操作。前台首页用例如图3-1所示。 （2）管理员功能需求 管理员登陆后，主要功能模块包括首页、个人中心、用户管理、卖家管理、旧物类型管理、旧物信息管理、置换交易管理、系统管理等功能。 关键词：旧物置换网站，Mysql数据库，Java技术 springboot框架

  • 上位机开发，对桥梁、环境等传感器传输的数据进行采集并入库，以便用于系统平台对数据进行处理分析(毕设&课设&实训&大作业&竞赛&项目)

    项目工程资源经过严格测试运行并且功能上ok，可实现复现复刻，拿到资料包后可实现复现出一样的项目，本人系统开发经验充足（全栈全领域），有任何使用问题欢迎随时与我联系，我会抽时间努力为您解惑，提供帮助 【资源内容】：包含源码+工程文件+说明（如有）等。答辩评审平均分达到96分，放心下载使用！可实现复现；设计报告也可借鉴此项目；该资源内项目代码都经过测试运行；功能ok 【项目价值】：可用在相关项目设计中，皆可应用在项目、毕业设计、课程设计、期末/期中/大作业、工程实训、大创等学科竞赛比赛、初期项目立项、学习/练手等方面，可借鉴此优质项目实现复刻，设计报告也可借鉴此项目，也可基于此项目来扩展开发出更多功能 【提供帮助】：有任何使用上的问题欢迎随时与我联系，抽时间努力解答解惑，提供帮助 【附带帮助】：若还需要相关开发工具、学习资料等，我会提供帮助，提供资料，鼓励学习进步 下载后请首先打开说明文件（如有）;整理时不同项目所包含资源内容不同;项目工程可实现复现复刻，如果基础还行，也可在此程序基础上进行修改，以实现其它功能。供开源学习/技术交流/学习参考，勿用于商业用途。质量优质，放心下载使用

Global site tag (gtag.js) - Google Analytics