你是精英。你熟记干净的代码，你梦想可靠的设计，你对你写的每一行都进行单元测试。你的代码是如此自我记录你甚至不需要写评论！
那么这个咆哮只适合你！因为让我告诉你一些事情：没有评论，使用你的代码仍然是痛苦的。无论你多么精英，你的代码多么棒，如果没有一些巧妙的解释，它仍然是一堆无法使用和无法维护的垃圾。
我以前从来没有咆哮过——至少在这里没有——但我现在必须这样做，否则我的头会爆炸！所以请原谅我的语气。冷静下来后，我会写一篇关于这个话题的更冷静的帖子。
自记录代码
下次我偶然发现你的界面或你的一类评论为零时，我发誓我会追捕你并咬断你的腿。
但是代码是自我记录的，你说？它是可靠的、格式良好的、使用富有表现力的名称、由简短的方法和类组成并且经过全面测试？它不需要评论？
一个关于合同的故事
让我们从一个故事开始……
想象一下，如果您被卡车撞到，您正在寻找一种保险来保护您的家人免于露宿街头。您决定了一项政策并向公司索取合同，以便您签署。但猜猜怎么了？他们不再做合同了！相反，他们采用了“工作公司胜过未读合同”的政策。
他们会很高兴地邀请您到他们的总部，在那里您可以自由地欣赏他们清晰的组织结构，在他们精心设计的建筑和公园周围散步，并与他们几千名细心的员工中的任何一个交谈。真的，你应该来，这些男人和女孩甚至有米奇和多萝西这样的好名字！
他们还想给你一份现有客户的名单。您可以给他们打电话，了解他们在公司的表现如何。考虑到他们的个人历史和付款方式，当他们出了什么事时，公司做了什么？顺便说一下，您甚至还可以参观 他们的 家！
所以，你问他们，这会怎样？很简单，只需开始给我们电汇月费，我们会为您提供保障，他们会回答。
很棒的自我记录保险政策！但是你会把你家人的幸福交给他们吗？
伊戈尔克拉克 。
测试
让我们回到代码。到现在为止，您可能能够发现商定行为和观察到的行为之间的区别。测试呢？我听到你问，他们没有定义预期的行为吗？
你在拖钓，对吧？现在我不仅要检查你的实现，还要检查一堆测试？因此，我现在没有编写代码，而是在研究数十种测试方法，希望找出一种能反映我的用例的方法？所有这些都可以推断出我是否可以期望不返回 null？
啊，是的。不幸的是，您甚至无法在单元测试中证明这一点。除非你设法用例子证明一个“适用于所有人”的定理，这将真正令人印象深刻。您无法在测试中清楚记录的其他内容？只有微不足道的细节，如线程安全（或缺乏线程安全）和不变性。
另外，如果你相信你的测试会记录你的代码，你最好确保人们因为没有达到 90%+ 的测试覆盖率而被解雇。根据我的经验，“不编写测试”和“不编写文档”的开发人员有相当多的重叠。
最后，你知道有多少社区会用 rtft 来回答问题——阅读 f**king 测试吗？不？那么我当时在想什么？
名字
但是你的名字很有表现力，你说？他们会挽救一天！真的吗？这是我在阅读文档时可能正在寻找的东西：
- 先决条件是什么，特别是关于我传递的论点？
- 关于返回值有什么承诺？
- 什么单位用于参数和返回值？
- 线程安全、可变性、不变性或依赖性如何？
- 在什么情况下会抛出异常？
不要告诉我你把所有这些都塞进了你的名字，因为你没有。不要告诉我它总是显而易见的，因为事实并非如此。顺便说一句，我也很想知道你为什么选择现在的设计。我想知道它如何适合变量名。
以及这种富有表现力的命名对于接口究竟是如何起作用的？我可以告诉你如何：一点也不！或者你希望我理解所有的十几个实现来找出它们是否应该是不可变的。
我也很好奇你的同事将如何实现一个未记录的接口。因为在我看来，他们基本上可以为所欲为。
猜测
所以下次你开始使用新图书馆时，吃你自己的狗粮。忽略文档！
如果密钥不存在，只需查看代码即可猜测 java 的 map.get 可能会返回什么。查看 concurrenthashmap 并告诉我是否允许空键。使用 guava 的 typetoken 或 cache 无需任何介绍。使用反射而不看评论。
你怎么说？这些都是api？这是完全不同的？严重地？！这他妈的有什么不同？我不在乎我是使用 api® 还是调用您的代码——要么它告诉我它做了什么，要么我去猜测。
猜测……因为如果你不告诉我发生了什么，我就会这么做。你真的认为我会通过你所有的五个实现和你的三位数单元测试来找出方法的作用吗？不！我会做出有根据的猜测，因为我很着急，必须完成。
这不是敏捷的目标吗？让开发者少猜？
说到敏捷
我们从“我们不写文档是因为我们讨厌它”变成了“我们不写文档是因为我们更重视工作代码而不是综合文档”。所以现在我们像以前一样忽略了文档，但我们终于被允许了，因为我们的代码突然变得很棒了？对对对……
所以请不要相信这个废话*，请注意敏捷宣言如何没有说“我们不写评论”。
老化评论
但评论年龄，你说？这就像说“车祸”。是的，它们偶尔会发生（顺便说一句，在大多数情况下，由于某种形式的疏忽会受到法律的惩罚），但这并不能阻止我们使用它们。这并不意味着我们没有责任试图阻止这种情况的发生。
另外，我很想知道您似乎正在使用那个神奇的编译器。一种防止包、类、字段、方法和变量名称老化的方法。在您更改代码时使它们保持最新和准确的一种。
哦，没有这种东西吗？震惊！你正在更新它们吗？恭喜！现在成为一个负责任的小开发人员，并将这些评论包含在该过程中，我们很好。
评论你他妈的代码！
所以，请不要自以为是，只在这里或那里添加有用的评论。在哪里？我会在下一篇文章中写到。