我有一个同事，他坚持认为他的代码不需要注释，这是“自文档”。
我已经审阅了他的代码，虽然它比我看到的其他人编写的代码更清晰，但我仍然不同意自文档化代码与经过注释和文档化的代码一样完整和有用。
帮我理解一下他的观点。
什么是自文档代码 它真的能取代注释良好和文档化的代码吗 在某些情况下，它是否比有良好文档和注释的代码更好 是否存在代码不可能在没有注释的情况下自文档化的例子
也许这只是我自身的局限性，但我看不出这怎么能成为一种好的练习。
这并不是一个争论——请不要提出为什么注释良好并有文档记录的代码是高优先级的原因——有很多资源都表明了这一点，但它们对我的同行来说并没有说服力。我认为我需要更全面地了解他的观点，才能说服他。如果你有必要，可以提出一个新的问题，但不要在这里争论。
另外，那些反对自我记录代码的人——这主要是为了帮助我理解自我记录代码传播者的观点(即积极的方面)。
当前回答
大多数文档/注释都是为了帮助未来的代码增强者/开发人员，从而使代码可维护。 通常情况下，我们会在稍后的时间回到我们的模块来添加新功能或优化。 在那个时候，通过简单地阅读注释来理解代码要比通过大量的断点来理解代码容易得多。 此外，我宁愿花时间思考新的逻辑，而不是破译现有的。
其他回答
您可能希望向您的同事指出的一件事是，无论他的代码是如何自我记录的，如果考虑并放弃了其他替代方法，那么该信息将丢失，除非他用该信息注释代码。有时，了解考虑了替代方案以及为什么不选择它同样重要，并且代码注释最有可能随着时间的推移而幸存下来。
在编写数学代码时，我有时发现写一篇类似文章的长注释很有用，解释数学、代码使用的符号约定以及它们是如何组合在一起的。我们在这里讨论的是数百行文档。
我试着让我的代码尽可能地自文档化，但当我几个月后重新开始工作时，我确实需要阅读解释，以免把它弄得乱七八糟。
当然，这种极端的措施在大多数情况下是不必要的。我认为这个故事的寓意是:不同的代码需要不同数量的文档。有些代码可以写得很清楚，以至于不需要注释——所以要写得清楚，不要在那里使用注释!
但是很多代码确实需要注释才能有意义，所以写得越清楚越好，然后使用尽可能多的注释……
这里的输入似乎非常复杂:)
我使用伪代码编程过程进行新的开发，这实际上使我的代码自文档化。我只在写新代码时才开始写伪代码，然后在上面扩展。我不是说这是最佳实践或类似的东西，我只是强调一个我认为有用的技巧，如果你知道你的代码需要大量的文档，如果它要交给第三方，审查者等等……它偶尔也会在我还没写一行代码的时候就给我指出一些问题。
' check database is available
' if it is then allow the procedure
' if it isnt roll back and tidy up
' move onto something else
变成了;
' check database is available
if checkDBStateResult(currentDB) = Open then
' if it is then allow the procedure
proc.Ok = True
else
' if it isnt roll back
proc.Ok = False
CleanUp()
end if
大多数文档/注释都是为了帮助未来的代码增强者/开发人员，从而使代码可维护。 通常情况下，我们会在稍后的时间回到我们的模块来添加新功能或优化。 在那个时候，通过简单地阅读注释来理解代码要比通过大量的断点来理解代码容易得多。 此外，我宁愿花时间思考新的逻辑，而不是破译现有的。
为什么代码之外的额外注释可能会更清晰，原因如下:
您正在查看的代码是自动生成的，因此对代码的任何编辑都可能在下次编译项目时失败 一个不太直接的实现被用来换取性能的提高(展开循环，为昂贵的计算创建查找表，等等)。
