目录
15.1 延迟的注释是糟糕的注释
15.2 先写注释
15.3 注释是一个设计工具
15.4 早期的注释很有趣
15.5 早期的注释代价高昂吗?
15.6 结论
许多开发人员将编写文档的工作推迟到开发过程的末尾, 即编码和单元测试完成之后. 这是产生低质量文档的最可靠的方法之一. 编写注释的最佳时间是在过程的开始, 即编写代码的时候. 首先编写注释使文档成为设计过程的一部分. 这不仅产生了更好的文档, 而且还产生了更好的设计, 并使编写文档的过程更加愉快.
15.1 延迟的注释是糟糕的注释
我遇到的几乎所有开发人员都推迟了写注释的时间. 当被问及为什么不更早地编写文档时, 他们说代码仍然在变化. 他们说, 如果他们很早就编写文档, 那么当代码发生变化时, 他们就必须重写文档; 最好等到代码稳定下来. 然而, 我怀疑还有另一个原因, 那就是他们把文档看作是苦力工作; 因此, 他们尽可能地拖延.
不幸的是, 这种方法有几个负面的后果. 首先, 延迟文档通常意味着根本不需要编写文档. 一旦你开始拖延, 很容易再拖延一点; 毕竟, 再过几周, 代码将更加稳定. 等到代码稳定下来的时候, 已经有很多了, 这意味着编写文档的任务已经变得非常艰巨, 甚至没有吸引力了. 从来没有合适的时间停下来几天, 把所有遗漏的注释都补上, 而且很容易让人觉得对项目来说最好的事情就是继续前进, 修复 bug 或者编写下一个新特性. 这将创建更多未归档的代码.
即使你有自律性回去写注释(不要欺骗你自己: 你可能没有), 注释也不会很好. 在这个过程的这个时候, 你已经在精神上离开了. 在你的脑海里, 这段代码已经完成了; 你急于开始下一个项目. 你知道写注释是正确的事情, 但它没有乐趣. 你只想尽快度过难关. 因此, 您可以快速地浏览代码, 添加足够的注释以使其看起来令人满意. 到目前为止, 您已经有一段时间没有设计代码了, 所以您对设计过程的记忆变得模糊了. 您在编写注释时查看代码, 因此注释重复了代码. 即使您试图重构代码中不明显的设计思想, 也会有您不记得的事情. 因此, 这些注释忽略了他们应该描述的一些最重要的事情.
15.2 先写注释
我用了一种不同的方法来写注释, 我把注释写在最开始:
对于一个新类, 我首先编写类接口注释.
接下来, 我为最重要的公共方法编写接口注释和签名, 但方法主体为空.
我对这些注释进行了一些迭代, 直到基本结构感觉正确为止.
此时, 我为类中最重要的类实例变量编写声明和注释.
最后, 我填写方法的主体, 根据需要添加实现注释.
在编写方法主体时, 我通常会发现需要额外的方法和实例变量. 对于每个新方法, 我都在方法体之前写接口注释; 对于实例变量, 我在编写变量声明的同时填写注释.
代码完成后, 注释也完成了. 从来没有积压的不成文的注释.
先注释的方法有三个好处:
首先, 它产生了更好的注释. 如果您在设计类时写下注释, 那么关键的设计问题就会在您的脑海中浮现出来, 所以很容易记录下来.
最好在每个方法的主体之前编写接口注释, 这样您就可以专注于方法的抽象和接口, 而不会被实现分散注意力.
在编码和测试过程中, 您将注意到并修复注释中的问题. 因此, 注释在发展的过程中不断改进.
15.3 注释是一个设计工具
在开始时编写注释的第二个好处 (也是最重要的一个好处) 是改进了系统设计. 注释提供了完全捕获抽象的唯一方法, 好的抽象是好的系统设计的基础. 如果您在开始时编写了描述抽象的注释, 那么您可以在编写实现代码之前对它们进行检查和调优. 要写出好的注释, 您必须识别一个变量或一段代码的本质: 这个东西最重要的方面是什么? 在设计过程的早期就这样做是很重要的, 否则你只是在破解代码.
注释就像是复杂煤矿中的金丝雀. 如果一个方法或变量需要很长的注释, 这是一个警告, 说明您没有一个好的抽象. 请记住, 在第 4 章中, 类应该是深入的: 最好的类具有非常简单的接口, 但是实现了强大的功能. 判断接口复杂性的最佳方法是根据描述它的注释. 如果方法的接口注释提供了使用该方法所需的所有信息, 并且很短很简单, 则表明该方法具有简单的 interface. 相反, 如果没有长而复杂的注释就无法完整地描述一个方法, 那么这个方法就有一个复杂的接口. 您可以将方法的接口注释与实现进行比较, 以了解该方法的深度: 如果接口注释必须描述实现的所有主要特性, 则该方法是肤浅的. 同样的思想也适用于变量: 如果需要很长的注释才能完整地描述一个变量, 这是一个危险信号, 表明您可能没有选择正确的变量分解. 总的来说, 编写注释的行为允许您尽早评估您的设计决策, 这样您就可以发现并修复问题.
危险信号: 难以描述
描述方法或变量的注释应该简单而完整. 如果你发现很难写这样的注释, 那就说明你所描述的东西的设计可能有问题.
当然, 注释只有在完整和清晰的情况下才能很好地指示复杂性. 如果您编写的方法接口注释没有提供调用该方法所需的所有信息, 或者注释非常晦涩, 难以理解, 那么该注释就不能很好地度量方法的深度.
15.4 早期的注释很有趣
尽早写注释的第三个也是最后一个好处是, 它让注释写作变得更有趣. 对我来说, 编程中最有趣的部分之一是新类的早期设计阶段, 在这个阶段, 我将充实类的抽象和结构. 我的大多数注释都是在这个阶段写的, 这些注释是我如何记录和测试我的设计决策的质量的. 我正在寻找的设计, 可以表达完整和明确的最少的语言. 注释越简单, 我对我的设计就感觉越好, 所以找到简单的注释是我的骄傲. 如果你是有策略地进行编程, 你的主要目标是一个伟大的设计, 而不是仅仅编写可以工作的代码, 那么编写注释应该是有趣的, 因为这是你识别最佳设计的方式.
15.5 早期的注释代价高昂吗?
现在, 让我们重新讨论延迟注释的理由, 即它避免了随着代码的发展而重新处理注释的成本. 一个简单的粗略计算将表明, 这并没有节省多少. 首先, 估计您在一起输入代码和注释所花费的开发时间, 包括修改代码和注释的时间; 这不太可能超过所有开发时间的 10%. 即使您的代码行总数的一半是注释, 编写注释也不会占用您全部开发时间的 5%. 把注释拖到最后只会节省其中的一小部分, 并不是很多.
首先编写注释将意味着在开始编写代码之前抽象将更加稳定. 这可能会节省编码期间的时间. 相反, 如果您先编写代码, 抽象可能会随着您的代码而发展, 这将比先注释的方法需要更多的代码修订. 当您考虑到所有这些因素时, 首先编写注释可能会更快.
15.6 结论
如果你还没有尝试过先写注释, 那就试试吧. 坚持到习惯为止. 然后考虑它如何影响您的注释质量, 设计质量和软件开发的整体享受. 在你尝试了一段时间后, 让我知道你的经验是否与我的相匹配, 为什么或为什么不.
来源: https://www.cnblogs.com/peida/p/12100547.html