只有代码会说实话

Only the Code Tells the Truth

程序的最终语义是给出可执行代码。如果它只有一段二进制码,就会非常难读懂!但如果你的程序是典型的商业软件开发、开源项目、或者动态解释语言的代码,它就应该可读。当你在阅读源码时,程序的意图就应该浮现出来。为了搞懂程序要做什么,最终你肯定要阅读源码。大多数精确的规范文档甚至都无法告诉你全部的真相:毕竟它无法容纳程序实际处理的全部细节,仅仅是高层次的需求分析。一份设计文档可能抓得住一部分设计规划,但它缺乏实现的必要细节。这些文档可能与当前的实现内容失去同步…或者就干脆放弃掉了,从一开始就没写过。而源码可能是唯一剩下的东西。

基于这一点,问一下自己要如何清爽地告诉你或者其他程序猿,你的代码要做什么。

你可能会说:“噢,我的注释就可以告诉你想要知道的任何内容。”但请记住,注释不是运行代码。它们会存在于文档一样形式的错误。流传着一种说法,注释理所当然是件好事,一些程序猿就不假思索地写越来越多的注释,甚至重复解释那些琐碎的已经很明确的代码。这对于阐明你的代码,完全是错误的。

如果你的代码需要注释,考虑重构它以免除注释。大量的注释会扰乱屏幕空间,甚至可能被IDE自动隐藏掉。如果你想要解释某个变更,那就在版本控制系统签入消息,而不是代码里。

你要做些什么才能让代码尽可能清晰地表达“真相”?争取一个好名字。结构化代码以内聚功能,选择简单的命名。解耦代码以实现正交性。编写自动测试来解释和检查接口的行为意图。当你学到更简约的代码或更好的解决方案时,果断重构。让你的代码尽可能地易于理解和阅读。

对待你的代码要像对待其他创作一样,如一首诗、一篇散文、一个博客、或是重要的email。仔细制作你要表达的内容,使其做它该做的,并尽可能直接传达出它正在做的事情;即便你离开后,它也能传达出你的意图。请记住,有用的代码会比预期使用更长时间。今后的维护者会感激你,如果你是维护者,并且你所处理的代码并不能轻易说明事实,请积极地应用上述准则。在代码中建立理智,并让自己保持理智。

0%