15.3 注释是一种设计工具

在开始时写注释的第二个，也是最重要的一个好处是，它可以改善系统的设计。注释提供了充分捕捉抽象的唯一方法，而好的抽象是好的系统设计的基础。如果你在一开始就写了描述抽象的注释，你就可以在写实现代码之前审查和调整它们。要写一个好的注释，你必须确定一个变量或一段代码的本质：这个东西最重要的方面是什么？在设计过程中尽早做到这一点是很重要的，否则你就只是在大幅删改代码。

如果将复杂性比作煤矿，那么注释就是金丝雀。如果一个方法或变量需要很长的注释，那就是一个危险信号，说明你没有一个好的抽象。请记住第四章的内容，类应该是深的：最好的类有非常简单的接口，但却实现了强大的功能。判断一个接口的复杂程度的最好方法就是看描述它的注释。如果一个方法的接口注释提供了使用该方法所需的所有信息，并且简短明了，这说明该方法有一个简单的接口。反之，如果没有长而复杂的注释就无法完整地描述一个方法，那么这个方法就有一个复杂的接口。你可以将一个方法的接口注释与实现进行比较，感受一下一个方法有多深：如果接口注释必须描述实现的所有主要特性，那么该方法就是浅的。同样的想法也适用于变量：如果需要很长的注释才能完全描述一个变量，那么这就是一个危险信号，表明你可能没有选择正确的变量分解方式。总的来说，写注释的行为可以让你尽早评估你的设计决策，这样你就可以发现并解决问题。

危险信号：难以描述

描述一个方法或变量的注释应该是简单而又完整的。如果你觉得写这样的注释很困难，那就说明你所描述的东西的设计可能有问题。

当然，只有在注释完整清晰的情况下，注释才是衡量复杂性的一个好指标。如果你写的方法接口注释没有提供调用该方法所需的所有信息，或者注释过于隐晦，难以理解，那么这个注释就不能很好地衡量该方法的深度。