背景

去年下半年，我在微信书架里加入了许多技术书籍，各种类别的都有，断断续续的读了一部分。

没有计划的阅读，收效甚微。

新年伊始，我准备尝试一下其他方式，比如阅读周。每月抽出1~2个非连续周，完整阅读一本书籍。

这个“玩法”虽然常见且板正，但是有效，已经坚持阅读十个月。

已读完书籍：《架构简洁之道》、《深入浅出的Node.js》、《你不知道的JavaScript（上卷）》、《你不知道的JavaScript（中卷）》、《你不知道的JavaScript（下卷）》、《数据结构与算法JavaScript描述》、《WebKit技术内幕》、《前端架构：从入门到微前端》、《秒懂算法：用常识解读数据结构与算法》、《JavaScript权威指南》、《JavaScript异步编程设计快速响应的网络应用》。

当前阅读周书籍：《编写可测试的JavaScript代码》。

人工测试

最后，和复杂度最相关的测试是合作者的测试。向她展示你的代码。她的反应是什么？她能理解它吗？能遵循它吗？理解它做了什么、为什么要这么做？这种非正式的代码审查过程是通向更正式审查的一个关口。Fagan对正式的软件检查进行的研究表明，可以找到所有程序Bug的60%到90%，这是一个令人难以置信的百分比。Fagan检验过程是一个非常正式的、可重复的、量化代码评审的过程，这里就不详细讨论了；然而值得一提的是，没有其他方法可以发现（甚至接近）如此大比例的Bug，因此要认真对待Fagan的检查结果。

再回到不那么严肃的话题，非正式的代码评审或走查，也是衡量复杂性、可维护性、可测试性的优秀工具。6个月后看到的代码不是现在的代码了，但别人可能会看到。即使能看到，可能也不记得自己做了什么，以及为什么这么做了。

这就是良好注释代码发挥作用的地方。到目前为止，我们已经讨论了什么样的代码会带来复杂性，以及如何降低这种复杂性。但是，没有所谓的零复杂性。编写软件是很困难的。编写好的软件则是难上加难。Douglas Crockford认为编写软件是人类最复杂的事情。通过大量的注释，可以有助于简化代码。

Enerjy研究表明，在3个容易错误代码指标中，有两个是基于注释的代码，也就是函数前面所命名的注释块。函数前面丢失或错误的注释块是导致易出错代码的最主要指标。

注释（正确的注释）需要对代码有一个完整的理解，越多的注释需要越多的理解。全面了解一个给定的函数究竟有多难？第一次编写一个函数时，正是最可能全面理解该函数到底在做什么的时候。这就是编写注释的时机。尝试一下在编写任何函数之前进行注释编写，就像使用驱动测试开发（TDD）在编写函数之前编写测试一样。未来，任何代码的更改也应该写注释。即便再也不会见到这段代码了，但别人会看到——你的代码可能会有Bug，而他不得不修复它。

注释也可以使代码更具可测试性。它们是判断测试什么以及如何测试的路标。注释强迫我们要理解代码，它们可以作为一种迷你的代码自我审核。尤其是不清楚函数可能的返回值范围以及这些返回值是何意义时，这就显得非常重要。函数前面的注释必须明确函数的输入参数是什么，以及返回值的意义。理想情况下，这种函数是没有副作用的，但是如果有副作用，则必须在注释块中进行显式声明。这表明你知道该函数有副作用，以及这些副作用到底是什么。

有趣的是，语句没有括号也是易出错代码的一个主要指标，所以记得一定要用括号！

总结

复杂性可以加大别人阅读代码的困难度。20分钟是一般成年人的专注力上界。一般来说，如果合作者需要花费超过20分钟去理解程序的要点——不是整个程序，而是从整体中提取出来的一个方法或对象——那就有问题了。我们有责任让代码变得可理解，少许的复杂性是不可避免的，而不是大量的复杂性都是不可避免的。

代码大小也是如此。代码大小会随着时间的增长而增长。最小化代码大小、最大化可理解性并不意味着限制应用程序中的代码数量。这意味着要限制每个函数、模块、或文件中的代码量。可以仍然有很多函数、模块和文件，没有关系的。只要单个尺寸是合理的，它们就是可理解的，要将复杂度保持在最低限度。

因此，当务之急是理解正在编写的代码。可以通过注释展示我们的理解，特别是当我们知道我们在打破“规则”时。如果连自己都无法从注释中解释为什么要这么做以及做什么，那别人就更没有办法理解了。一旦别人开始维护我们的代码，就可能会出现糟糕的Bug，并且代码很可能被新来的维护者取消并重写。真是浪费啊！还是第一次就写对吧！

作者介绍
非职业「传道授业解惑」的开发者叶一一。
《趣学前端》、《CSS畅想》等系列作者。华夏美食、国漫、古风重度爱好者，刑侦、无限流小说初级玩家。
如果看完文章有所收获，欢迎点赞👍 | 收藏⭐️ | 留言📝。