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

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

帮我理解一下他的观点。

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

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

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

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


当前回答

这将完全取决于团队在文档中的价值。我建议记录为什么/意图而不是如何是重要的,这并不总是在自记录代码中捕获。获取/设置没有这些是显而易见的-但计算,检索等一些为什么应该表达。

如果你来自不同的国家,你也要意识到你的团队中的差异。措辞上的差异会影响到方法的命名:

BisectionSearch

BinarySearch

二进制斩

这三种方法都是由在3个不同大洲接受过培训的开发人员提供的。只有通过阅读描述算法的注释,我们才能识别库中的重复。

其他回答

“自文档化”代码背后的思想是,代码中的实际程序逻辑非常清楚,不仅可以向阅读代码的人解释代码在做什么,还可以向他们解释为什么要这样做。

在我看来,真正的自文档代码的想法是一个神话。代码可以告诉您正在发生的事情背后的逻辑,但它不能解释为什么要以某种方式完成,特别是如果有不止一种方法来解决问题。仅仅因为这个原因,它永远不能取代注释良好的代码。

自文档化代码是一种很好的实践,如果操作得当,可以轻松地传达代码的含义,而无需阅读太多注释。特别是在团队中的每个人都很好地理解该领域的情况下。

话虽如此,评论对于新手、测试人员或生成文档/帮助文件都非常有帮助。

自文档化代码+必要的注释将大大有助于跨团队的人员。

我会扭转局面。

问问自己在他的代码中有什么不理解的,然后让他把这些记录下来。也许你也可以告诉我们一些。

已经提出的观点是,评论应该捕捉意图,但我想再深入一点。

我认为对于任何一类问题,都有一个理想的(或几乎是这样的)词汇和语法来描述它,如果你只是让遇到这类问题的人来描述它们(假设那个人能清晰地思考),你就能看到它。

如果词汇和语法可以很容易地(通过定义类、方法等)映射到计算机语言的代码上,那么这些代码可以是自文档化的。此外,IMO还创建了一种特定于领域的语言。(这就是我对“陈述性”的粗略定义。)

如果不能实现这个理想,如果问题不能直接映射到计算机代码上,那么就需要将两者联系起来。在我看来,这就是评论的目的。

这样,当问题发生变化时,您就可以找到相应的代码部分进行更改。

编辑:顺便说一下,我并不支持OOP方法论,即每个名词都变成一个类,每个动词都变成一个方法。我已经看过足够多的臃肿软件了。

我认为——就像你们中的许多人一样——要真正实现自文档化,代码需要显示某种形式的意图。但是我很惊讶没有人提到BDD——行为驱动开发。这个想法的一部分是,你有自动化的测试(代码)来解释你的代码的意图,这是很难明显的。

Good domain modeling 
+ good names (variabes, methods, classes) 
+ code examples (unit tests from use cases) 
= self documenting software