一篇被低估的关于编程的文章

来源

这篇medium文章中，作者的原意是说明通过哪些方法减少代码的注释，但是作为一篇关于如何写出更好的可维护代码的文章来看也很有意义。

编写可维护的代码和设计可维护的架构是程序员最基本，也是最重要的能力，没有之一，因为只有当代码和系统可以维护，才能不断升级，才能生存下去，才能发光发热。至于其它的所谓高并发高性能的架构和代码反而是其次的了，只是因为业务需要进行的一些改进，但是改进的基础都是可维护性。

主要内容

没有废话，直接说重点

运行日志（Logging）

首先代码中肯定有类似这样的日志：

// Now we are going to convert Thing-Amajig-A to Thing-Amajig-B
复制代码

如果改成

logger.info(“Now we are going to convert Thing-Amajig-A to Thing-Amajig-B”)
复制代码

不仅可以加一些简单的说明，而且当代码运行的时候，可以作为系统的输出信息，和系统运行的上下文结合，可以为代码的理解添加更多的信息，不管是别人接手代码，还是自己过了好长时间重新维护系统，都让事情变得更加简单

必要的测试（Testing—“Show, don’t tell”）

面对一个功能相对来说复杂，或者实现比较绕的实现，通常是将当时实现的场景和思路在注释或者文档中进行说明，但是可能说得不清楚，或者之后阅读者对说明的理解有自己的偏差，或者实现改变了，注释或者文档忘记了，这些最终造成的结果只有一个：当初的实现没法弄明白了，只能重写。这是一个重大的损失。

解决的方案就是将关键实现的测试代码写出来，测试的过程就是使用的过程，让人一看就明白输入和输出分别是什么；同时及时修改了代码，因为测试可能通不过，就必须将测试顺便修改，也就是同步文档的过程，这样就不会造成代码的不清不楚。

优秀的命名（Good Naming）

这个就是老生常谈了，计算机界两件事最难，一个是算法和数据结构，一个就是为变量和函数命名。难的最根本原因就是因为命名非常重要，所以好好琢磨一下有重大意义

模块化（Separation of Concerns）

将多个事情放在一起说基本每件事情都说不清楚，说清楚的方法都是掰开揉碎了一件件说。

每个小模块要完成什么基本的功能，几个小模块组合起来完成了更高层的功能，这些都是首先要把要做的事情搞清楚，然后好好的设计一下谁先谁后，谁是底层依赖，谁是上层抽象，这些都搞得清晰了，代码的模块化才能搞好，也更好维护。

模块化的好处不只是容易阅读，也容易替换，加在一起就是容易维护。写过的代码都是耗费了精力的，过一段时间就丢弃相当于丢弃了时间和金钱，和钱过不去这是不可饶恕的。

领域化（Specification）

这个方面一般人可能接触就相对少一点。

如果有语言的支持（一般lisp类语言都可以），通过宏编程，让系统实现越来越直接，也就是每行代码越来越贴近业务本身，不仅没有多余的说明，而且更有业务逻辑的自我限制，那最终的代码就是功能实现简明，并且代码量也少。

找了好多语言，不是语言本身在宏编程上实现的不好，就是语言的生态不够，无法在生产中使用。如果有推荐的，请给我留言。

总结

系统的文档说明的重要性毋庸置疑，但是文档的实现方式值得好好思索。

关于系统的长期整体架构，应该专门通过文字和图说明，但是细节的东西更应该脱离于外部说明，而更依赖于系统本身，毕竟只要不在一起，外部的文档和系统细节的变化总是不能同步。

放弃外部文档对细节的说明，转而更依赖代码本身，不仅能够表现出对系统的精确和实时的说明，也可以让外部文档的说明范围更加精简，从而最终得到准确和实时的整体的系统文档。