第 12 章 为什么写注释？四个理由

Chapter 12 Why Write Comments? The Four Excuses

In-code documentation plays a crucial role in software design. Comments are essential to help developers understand a system and work efficiently, but the role of comments goes beyond this. Documentation also plays an important role in abstraction; without comments, you can’t hide complexity. Finally, the process of writing comments, if done correctly, will actually improve a system’s design. Conversely, a good software design loses much of its value if it is poorly documented.

代码内文档在软件设计中起着至关重要的作用。注释对于帮助开发人员理解系统和有效工作至关重要，但是注释的作用不止于此。文档在抽象中也起着重要作用。没有注释，您就无法隐藏复杂性。最后，编写注释的过程（如果正确完成）将实际上改善系统的设计。相反，如果没有很好的文档记录，那么好的软件设计会失去很多价值。

Unfortunately, this view is not universally shared. A significant fraction of production code contains essentially no comments. Many developers think that comments are a waste of time; others see the value in comments, but somehow never get around to writing them. Fortunately, many development teams recognize the value of documentation, and it feels like the prevalence of these teams is gradually increasing. However, even in teams that encourage documentation, comments are often viewed as drudge work and many developers don’t understand how to write them, so the resulting documentation is often mediocre. Inadequate documentation creates a huge and unnecessary drag on software development.

不幸的是，这种观点并未得到普遍认同。生产代码的很大一部分基本上不包含任何注释。许多开发人员认为注释是浪费时间。其他人则看到了注释中的价值，但不知何故从不动手编写它们。幸运的是，许多开发团队认识到了文档的价值，并且感觉这些团队的普及率正在逐渐提高。但是，即使在鼓励文档的团队中，注释也经常被视为繁琐的工作，而且许多开发人员也不了解如何编写注释，因此生成的文档通常是平庸的。文档不足会给软件开发带来巨大且不必要的拖累。

In this chapter I will discuss the excuses developers use to avoid writing comments, and the reasons why comments really do matter. Chapter 13 will then describe how to write good comments and the next few chapters after that will discuss related issues such as choosing variable names and how to use documentation to improve a system’s design. I hope these chapters will convince you of three things: good comments can make a big difference in the overall quality of software; it isn’t hard to write good comments; and (this may be hard to believe) writing comments can actually be fun.

在本章中，我将讨论开发人员避免写注释的借口，以及注释真正重要的原因。然后，第 13 章将描述如何编写好的注释，其后的几章将讨论相关问题，例如选择变量名以及如何使用文档来改进系统的设计。我希望这些章节能使您相信三件事：好的注释可以对软件的整体质量产生很大的影响；写好注释并不难；并且（可能很难相信）写注释实际上很有趣。

When developers don’t write comments, they usually justify their behavior with one or more of the following excuses:

当开发人员不写注释时，他们通常会以以下一种或多种借口为自己的行为辩护：

  • “Good code is self-documenting.”
  • “I don’t have time to write comments.”
  • “Comments get out of date and become misleading.”
  • “The comments I have seen are all worthless; why bother?” In the sections below I will address each of these excuses in turn.
  • “好的代码可以自我记录。”
  • “我没有时间写注释。”
  • “注释过时，并会产生误导。”
  • “我所看到的注释都是毫无价值的；何必？” 在以下各节中，我将依次讨论这些借口。