我有一个同事,他坚持认为他的代码不需要注释,这是“自文档”。
我已经审阅了他的代码,虽然它比我看到的其他人编写的代码更清晰,但我仍然不同意自文档化代码与经过注释和文档化的代码一样完整和有用。
帮我理解一下他的观点。
什么是自文档代码
它真的能取代注释良好和文档化的代码吗
在某些情况下,它是否比有良好文档和注释的代码更好
是否存在代码不可能在没有注释的情况下自文档化的例子
也许这只是我自身的局限性,但我看不出这怎么能成为一种好的练习。
这并不是一个争论——请不要提出为什么注释良好并有文档记录的代码是高优先级的原因——有很多资源都表明了这一点,但它们对我的同行来说并没有说服力。我认为我需要更全面地了解他的观点,才能说服他。如果你有必要,可以提出一个新的问题,但不要在这里争论。
另外,那些反对自我记录代码的人——这主要是为了帮助我理解自我记录代码传播者的观点(即积极的方面)。
好的设计结构有助于指出,有些函数是通用的,有些是随机的业务逻辑,即使你没有评论说“这个函数是通用的”。
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.
还要考虑功能的可跟踪性。当你有了你的手册,那么你应该能够追踪到源代码的特性,并返回更好的可维护性。手册和规范与编程没有太大关系,但它们与软件工程有关。软件越大,需要的工程设计就越多。
已经提出的观点是,评论应该捕捉意图,但我想再深入一点。
我认为对于任何一类问题,都有一个理想的(或几乎是这样的)词汇和语法来描述它,如果你只是让遇到这类问题的人来描述它们(假设那个人能清晰地思考),你就能看到它。
如果词汇和语法可以很容易地(通过定义类、方法等)映射到计算机语言的代码上,那么这些代码可以是自文档化的。此外,IMO还创建了一种特定于领域的语言。(这就是我对“陈述性”的粗略定义。)
如果不能实现这个理想,如果问题不能直接映射到计算机代码上,那么就需要将两者联系起来。在我看来,这就是评论的目的。
这样,当问题发生变化时,您就可以找到相应的代码部分进行更改。
编辑:顺便说一下,我并不支持OOP方法论,即每个名词都变成一个类,每个动词都变成一个方法。我已经看过足够多的臃肿软件了。