请注释你那该死的代码

程序员文章站 2022-05-24 12:46:18

...

我站出来就是为了要说一句：

请注释你那该死的代码。

每次我遇到一个程序员——有时是相当高水平的——总发现他会认为：你并不需要给你的代码加注释。我要说，这就是胡说八道。我很长时间以来一直这么表达。问题是，让事情改变要比你想象的难。虽然我们正处在努力编写那些讨厌的代码、准备发布一些会令人惊叹的新东西的紧要关头，我们仍然几乎注释所有的东西。没有任何借口不去做这些事情。每隔3到7行代码，你就能看到有长篇的社论发表。有时，几百行代码里，你就能找到一个很好的笑话。

错误的藏身之处

看，一个是你想要的，一个是你实现的。你的bug就在这两者之间。如果写了注释，你就是在告诉我你想要的。而你的代码中告诉我你是如何去做的。程序的缺陷要么存在于你想要的想法中，要么，需求是对的，而你的代码有问题。请帮助我，让我知道究竟是哪个错了。

不要偷懒

一个常见的反对声音是：我听说，注释经常会过期，因为代码会经常更新，而注释不会。你不更新注释吗？你的同事也不？不要偷懒，不要养成一个让人认为偷点儿懒无所谓的文化氛围。告诉同事你是如何一丝不苟的注释程序的，让他们知道你也希望他们这样去做。说不注释是因为怕某人或某些地方在将来会造成你的错误，这只是在找借口。

你是有经验的人

人本无知，这很自然，但你是有经验的人。因此，你有义务教育那些需要学习的人。你的注释会指导那些正在阅读你的代码的人。告诉他们为什么在这里要用 Tuple数据结构，而不是用其它的(更好的做法是附加一个stack overflow或dotnetperls上的链接 … 你完全可以做到这些，不是吗？)你在这走了一个什么捷径？如果不走捷径你就不能按时发布，所以，告诉这些新手你遇到的特殊情况。否则的话，最终你的不好的代码将会被四处拷贝，四处散播。看！你写的烂代码变成了公司的程序模板！完全没有注释！

你会打字

我的招聘过程有一部分是白板编程，一部分是键盘编程。所有好的程序员都是打字高手。就说你每分钟能打出40-60词。那请你告诉我，为什么在你机枪扫射似的编写代码时不加上注释呢？当然，你可以花30秒时间告诉我，代码写的这样一团糟是因为搞业务的那个家伙需要程序在本周发布而换回不菲的7.5万美元。可是下个月呢？这些代码不要了？封存到石头里了？我知道这些代码是在干什么。但请告诉我你的意图。

你在一天天变老

听我说，我编程已经很久了，也许早在你上中学之前。我仍然在编程，我仍然喜欢编程。有朝一日，你也会变的跟我一样老。如果你到了像我一样(那时我已经没有能力再教育你)，那时，有太多的层，有太多的抽象，有太多的技术架构，你无法完全记住。你的注释就能出来指导你。它们会告诉你，6个月前，你是用这种方法、这种模式实现的，而且这样做只是为了炫耀。如果你是一个真正优秀——并且仍然在做编程的程序员——你会认识到，这些代码写的很烂，你现在需要以不同的方式重新实现它。而你仍然有你的注释来让你回忆起当时的想法和为什么这样做。