我有一个同事,他坚持认为他的代码不需要注释,这是“自文档”。

我已经审阅了他的代码,虽然它比我看到的其他人编写的代码更清晰,但我仍然不同意自文档化代码与经过注释和文档化的代码一样完整和有用。

帮我理解一下他的观点。

什么是自文档代码 它真的能取代注释良好和文档化的代码吗 在某些情况下,它是否比有良好文档和注释的代码更好 是否存在代码不可能在没有注释的情况下自文档化的例子

也许这只是我自身的局限性,但我看不出这怎么能成为一种好的练习。

这并不是一个争论——请不要提出为什么注释良好并有文档记录的代码是高优先级的原因——有很多资源都表明了这一点,但它们对我的同行来说并没有说服力。我认为我需要更全面地了解他的观点,才能说服他。如果你有必要,可以提出一个新的问题,但不要在这里争论。

另外,那些反对自我记录代码的人——这主要是为了帮助我理解自我记录代码传播者的观点(即积极的方面)。


当前回答

来自非评论阵营的一些观点。

“注释良好”(冗长)的代码更难阅读和理解。首先,有更多的文本需要扫描。它增加了理解CodeBase的认知努力——非功能性文本占用了屏幕上可以用来显示代码的空间。

注释的另一个大问题是它们不可靠——尤其是在旧的代码库中,注释腐烂比位腐烂发生得更快。

当然,还有写评论的工作。除了偶尔的一行注释之外,每次我开始注释代码时,都会有两种负罪感

这个信息需要在整个支持文档中 我需要清理我的代码

其他回答

我认为自记录代码是注释的一个很好的替代品。如果您需要注释来解释代码是如何或为什么是这样的,那么您应该修改函数或变量名以使其更具解释性。这可能取决于编码器是否会用注释或重命名一些变量和函数并重构代码来弥补不足。

但是,它并不能真正取代您的文档,因为文档是您提供给其他人用来解释如何使用您的系统的,而不是它是如何工作的。

编辑:我(可能还有其他所有人)应该有一个数字信号处理(DSP)应用程序应该很好地注释的规定。这主要是因为DSP应用程序本质上是2 for循环,提供了数组的值和添加/乘以/等等所说的值…要更改程序,您需要更改其中一个数组中的值…需要一些评论来说明在这种情况下你在做什么;)

当你阅读“自文档代码”时, 你看它在做什么, 但你不能总是猜测它为什么会以那种特定的方式运行。

有大量的非编程约束 比如业务逻辑、安全性、用户需求等。

当您进行维护时,这些背景信息变得非常重要。

只是我的一小撮盐……

在我看来,任何代码都应该是自记录的。在良好的、自文档化的代码中,您不必解释每一行,因为每个标识符(变量、方法、类)都有一个明确的语义名称。过多的注释实际上会使代码更难阅读(!),所以如果您的同事

为每个类、成员、类型和方法and编写文档注释(Doxygen、JavaDoc、XML注释等) 清楚地注释代码中没有自文档化AND的部分 为每个代码块写一个注释来解释意图,或者代码在更高抽象级别上做了什么(例如,找到所有大于10mb的文件,而不是遍历目录中的所有文件,测试文件大小是否大于10mb,如果为真则返回)

在我看来,他的代码和文档都很好。请注意,自文档化的代码并不意味着不应该有注释,而只是不应该有不必要的注释。然而,问题是,通过阅读代码(包括注释和文档注释)应该立即理解代码的功能和原因。如果“自文档化”代码比注释代码需要更长的时间来理解,那么它就不是真正的自文档化。

来自非评论阵营的一些观点。

“注释良好”(冗长)的代码更难阅读和理解。首先,有更多的文本需要扫描。它增加了理解CodeBase的认知努力——非功能性文本占用了屏幕上可以用来显示代码的空间。

注释的另一个大问题是它们不可靠——尤其是在旧的代码库中,注释腐烂比位腐烂发生得更快。

当然,还有写评论的工作。除了偶尔的一行注释之外,每次我开始注释代码时,都会有两种负罪感

这个信息需要在整个支持文档中 我需要清理我的代码

好的设计结构有助于指出,有些函数是通用的,有些是随机的业务逻辑,即使你没有评论说“这个函数是通用的”。

We should not forget about design and specification documentation though. Those have or at least should have much of the texts that are not necessarily needed in comments. Software often have also user manuals and other description documents, and those should be in sync with what the program does. The situation is not great if the user has to find out what the software does from the source code instead of a manual. So self documenting code still doesn't mean that the actual software has been documented.

还要考虑功能的可跟踪性。当你有了你的手册,那么你应该能够追踪到源代码的特性,并返回更好的可维护性。手册和规范与编程没有太大关系,但它们与软件工程有关。软件越大,需要的工程设计就越多。