代码是灵魂，注释是心声

资讯频道 → 非技术

0顶
0踩

2014-11-26 15:58 by 正式编辑 cao345657340 评论(1) 有4766人浏览

编程工作情感

在以前一些关于代码注释的文章中，我发现，你不需要的注释才是最好的注释。不要急着批判，请允许我阐述一下。首先代码应该尽量地简洁，尽可能地做到不需要依赖注释就可以理解。只有那些真的没法更易于理解的代码，才需要我们添加注释。

有一本非常经典的书叫《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文件中呢？

的确，这一点都不难。归根究底，代码只会告诉你程序是如何工作的，但是注释则能说明工作的原因。所以，下次你写代码的时候，不妨在这两个方面给你的同事做个榜样。

查看图片附件

来自: 码农网

分享到：

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安装下载

基于SSM+JSP+HTML的东风锻造有限公司重大停管理系统(Java毕业设计，附源码，数据库，教程）.zip

Java 项目， Java 毕业设计，Java 课程设计，基于 ssm 开发的，含有代码注释，新手也可看懂。毕业设计、期末大作业、课程设计、高分必看，下载下来，简单部署，就可以使用。包含：项目源码、数据库脚本、软件工具等，前后端代码都在里面。该系统功能完善、界面美观、操作简单、功能齐全、管理便捷，具有很高的实际应用价值。项目都经过严格调试，确保可以运行！ 1. 技术组成前端：jsp 后台框架：SSM 开发环境：idea 数据库：MySql（建议用 5.7 版本，8.0 有时候会有坑）数据库工具：navicat 部署环境：Tomcat（建议用 7.x 或者 8.x 版本）， maven 2. 部署如果部署有疑问的话，可以找我咨询 Java工具包下载地址： https://pan.quark.cn/s/eb24351ebac4

数据库系统课程设计报告-体育项目比赛管理系统设计与开发

一、系统需求分析 1 （一）需求概述 1 （二）业务流分析 1 从运动员角度分析 1 （三）数据流分析 4 （四）数据字典 5 二、数据库概念结构设计 6 （一）实体分析 6 （二）属性分析 6 （三）联系分析 8 （四）概念模型分析（.PDM图） 9 三、数据库逻辑结构设计 9 （一）概念模型转化为逻辑模型 9 1.一对一关系的转化 9 2.一对多关系的转化 9 3.多对多关系的转化 10 （二）逻辑模型设计（.PDM图） 10 四、数据库物理实现（一）表设计 10 （一）表设计 10 （二）创建表和完整性约束代码设计 11 五、数据库功能调试 15 （一）运动员管理模块 15 （二）负责人管理模块 16 （三）系统管理员管理模块 17 六、设计系统前台软件 21 （一）开发软件选择 21 （二）软件功能要求与设计 22 （三）软件功能实现 22 （四）系统测试 24 七、设计总结 27

基于SSM+JSP的文物管理系统+数据库（Java毕业设计，包括源码，教程）.zip

Java 项目， Java 毕业设计，Java 课程设计，基于 SpringBoot 开发的，含有代码注释，新手也可看懂。毕业设计、期末大作业、课程设计、高分必看，下载下来，简单部署，就可以使用。包含：项目源码、数据库脚本、软件工具等，前后端代码都在里面。该系统功能完善、界面美观、操作简单、功能齐全、管理便捷，具有很高的实际应用价值。项目都经过严格调试，确保可以运行！ 1. 技术组成前端：jsp 后台框架：SSM 开发环境：idea 数据库：MySql（建议用 5.7 版本，8.0 有时候会有坑）数据库工具：navicat 部署环境：Tomcat（建议用 7.x 或者 8.x 版本）， maven 2. 部署如果部署有疑问的话，可以找我咨询 Java工具包下载地址： https://pan.quark.cn/s/eb24351ebac4

智慧园区整体解决方案-37PPT(46页).pptx

智慧园区，作为现代化城市发展的新兴模式，正逐步改变着传统园区的运营与管理方式。它并非简单的信息化升级，而是跨越了行业壁垒，实现了数据共享与业务协同的复杂运行系统。在智慧园区的构建中，人们常常陷入一些误区，如认为智慧园区可以速成、与本部门无关或等同于传统信息化。然而，智慧园区的建设需要长期规划与多方参与，它不仅关乎技术层面的革新，更涉及到管理理念的转变。通过打破信息孤岛，智慧园区实现了各系统间的无缝对接，为园区的科学决策提供了有力支持。智慧园区的核心价值在于其提供的全方位服务与管理能力。从基础设施的智能化改造，如全面光纤接入、4G/5G网络覆盖、Wi-Fi网络及物联网技术的运用，到园区综合管理平台的建设，智慧园区打造了一个高效、便捷、安全的运营环境。在这个平台上，园区管理方可以实时掌握运营动态，包括道路状况、游客数量、设施状态及自然环境等信息，从而实现事件的提前预警与自动调配。同时，智慧园区还为园区企业提供了丰富的服务，如项目申报、资质认定、入园车辆管理及统计分析等，极大地提升了企业的运营效率。此外，智慧园区还注重用户体验，通过信息发布系统、服务门户系统及各类智慧应用，如掌上营销、智慧停车、智能安防等，为园区员工、企业及访客提供了便捷、舒适的生活与工作体验。值得一提的是，智慧园区还充分利用大数据、云计算等先进技术，对园区的能耗数据进行采集、分析与管理，实现了绿色、节能的运营目标。在智慧园区的建设过程中，还涌现出了许多创新的应用场景。例如，在环境监测方面，智慧园区通过集成各类传感器与监控系统，实现了对园区水质、空气质量的实时监测与预警；在交通管理方面，智慧园区利用物联网技术，对园区观光车、救援车辆等进行实时定位与调度，提高了交通效率与安全性；在公共服务方面，智慧园区通过构建统一的公共服务平台，为园区居民提供了包括平安社区、便民社区、智能家居在内的多元化服务。这些创新应用不仅提升了园区的智能化水平，还为园区的可持续发展奠定了坚实基础。同时，智慧园区的建设也促进了产业链的聚合与发展，通过搭建聚合产业链平台，实现了园区内企业间的资源共享与合作共赢。总的来说，智慧园区的建设不仅提升了园区的综合竞争力，还为城市的智慧化发展树立了典范。它以用户需求为导向，以技术创新为驱动，不断推动着园区向更加智慧、高效、绿色的方向发展。对于写方案的读者而言，智慧园区的成功案例与创新应用无疑提供了宝贵的借鉴与启示，值得深入探索与学习。

Java毕业设计-SpringBoot+Vue的基于SpringBoot的冬奥会科普平台（附源码、数据库、教程）.zip

Java 项目， Java 毕业设计，Java 课程设计，基于 SpringBoot 开发的，含有代码注释，新手也可看懂。毕业设计、期末大作业、课程设计、高分必看，下载下来，简单部署，就可以使用。包含：项目源码、数据库脚本、软件工具等，前后端代码都在里面。该系统功能完善、界面美观、操作简单、功能齐全、管理便捷，具有很高的实际应用价值。项目都经过严格调试，确保可以运行！ 1. 技术组成前端：html、javascript、Vue 后台框架：SpringBoot 开发环境：idea 数据库：MySql（建议用 5.7 版本，8.0 有时候会有坑）数据库工具：navicat 部署环境：Tomcat（建议用 7.x 或者 8.x 版本）， maven 2. 部署如果部署有疑问的话，可以找我咨询 Java工具包下载地址： https://pan.quark.cn/s/eb24351ebac4 后台路径地址：localhost:8080/项目名称/admin/dist/index.html 前台路径地址：localhost:8080/项目名称/front/index.html （无前台不需要输入）

0顶0踩