如今评论比以往任何时候都容易。在Java中，有一些将注释链接到类的很好的技术，而Java IDE擅长为您创建注释外壳。像Clojure这样的语言甚至都允许您在函数代码本身中添加对函数的描述作为参数。
但是，我们仍然生活在一个时代，好开发者经常发表过时或较差的评论-我对提高评论的鲁棒性和实用性很感兴趣。
特别是在这里，我对Java / Clojure / Python感兴趣，但是答案不需要特定于语言。
是否有任何新兴技术可以验证注释并自动检测“模糊”注释（例如，带有魔术数字的注释，不完整的句子等）或不正确的注释（例如，检测拼写错误的变量等）。
更重要的是：那里是否存在公认的“评论政策”或策略？那里有很多关于如何编码的建议-但是“如何发表评论”呢？
Answers:
名称/文档会告诉你什么，你在做什么。
实施应该告诉你如何你正在做它。
注释应告诉您为什么要按照自己的方式进行。
这可能会引起争议，但是我的建议是尽可能写FEW评论。改用漂亮的，清晰的类名，变量名和方法名。以最清晰的方式编写代码；并认为这是代码中最重要的属性（除了满足要求之外）。仅当您已使方法尽可能清晰时才写评论，并且您仍然认为它需要进一步说明。
并且具有组织上的惯例，即任何人以任何方式更改班级时，都必须确保评论仍然正确。
if (a == b) then c();，但是如果我不知道为什么会这样-那是应该使用评论的时间：)
doxygen是找到如何使用代码注释自动生成文档的最权威的位置之一。虽然可以给我更多这样的工具。
这定义了注释编写的标准，应该遵循该标准来自动生成文档。但是，这提供了更多的结构，但没有语义上的验证。例如，它无法检查您是否使用了误导性的英语来描述功能的目的！
虽然这是使注释结构化的最好方法，但我个人认为需要更多文档来使代码更具可维护性。一段时间以前，P.SE中存在一个问题。代码可以作为开源开发人员工具中的文档吗？多久一次？当然，这也适用于非开源项目。
为了使代码更易于维护-实际上，更重要的是存在一个外部文档来帮助创建如何对待代码的结构，然后应限制代码内部的注释以查看
我认为，如果要定义注释编写的策略，则应将其作为编码标准中包括的整体方法。看到这个：在开发团队中引入样式指南和文档生成软件可能会有什么陷阱？
通常，注释占不到代码的5％。而且在实践中，虽然代码审查本身引起的关注要少得多（在开发的其他方面），但也很难对注释进行审查。
是否有任何新兴技术可以验证注释并自动检测“模糊”注释（例如，带有魔术数字的注释，不完整的句子等）或不正确的注释（例如，检测拼写错误的变量等）。
有一个众所周知的技术-它被称为“代码审查”，并有一个姐妹叫做“配对编程”。不要在这里“自动地”期望任何东西。
更重要的是：是否有公认的“评论政策”或策略？关于如何编码，这里有很多建议，但是“如何发表评论”呢？
“代码完成”不仅包含有关如何编码的所有内容，还包含有关“如何注释”的章节，尤其是有关如何编写自文档代码的章节。
我最喜欢的一种特定于Java的资源是Oracle的《如何为Javadoc工具编写文档注释》：
本文档描述了在Java软件Sun Microsystems编写的Java程序的文档注释中使用的样式指南，标签和图像约定。
如果要使用某个API，则必须对其进行记录。传统上，API文档是手动生成的，因此要使其与代码保持同步是一件很麻烦的事情。Java编程环境通过Javadoc实用程序简化了此任务。Javadoc通过带有特殊格式的文档注释（通常称为doc注释）的源代码自动生成API文档。
来自有效Java第二版。