内联代码注释的最佳方法是什么？

我们正在对已有20年历史的旧代码库进行一些重构，并且我正在与我的同事讨论代码中的注释格式（plsql，java）。

没有默认的注释格式，但是在大多数情况下，人们会在注释中执行以下操作：

// date (year, year-month, yyyy-mm-dd, dd/mm/yyyy), (author id, author name, author nickname) and comment

我想要的将来和过去评论的建议格式是：

// {yyyy-mm-dd}, unique_author_company_id, comment

我的同事说，我们只需要评论，并且必须将所有过去和将来的评论重新格式化为这种格式：

// comment

我的论点：

• 我说出于维护原因，知道何时以及谁进行了更改非常重要（即使此信息在SCM中也是如此）。
• 该代码是有效的，因此有历史。
• 因为没有更改日期，如果不打开SCM工具并搜索较长的对象历史记录，就无法知道何时进行更改。
• 因为作者非常重要，所以改变作者比改变作者更可信
• 敏捷性原因，无需打开和浏览SCM工具
• 人们会更害怕更改某人15年前所做的事情，而不是最近创建或更改的事情。
• 等等

我同事的论点：

• 历史在SCM中
• 开发人员不得直接在代码中了解代码的历史记录
• 软件包的长度为15,000行，而且非结构化的注释使这些软件包更难以理解

您认为最好的方法是什么？还是您有更好的方法来解决此问题？

普通的留言

我非常相信评论的原因是（而不是如何）。当您开始添加有关您如何陷入问题的注释时，没有什么要求强制保留与代码相关的注释（为什么通常不会更改（为什么解释会随着时间的推移而有所增强））。

以同样的方式，就为什么用这种方式完成代码而言，date / authorInfo不会给您带来任何好处。就像它会随着时间的流逝而退化一样，因为没有任何工具可以强制执行。同样，相同的信息已经存储在源代码控制系统中（因此，您的工作量很大（但可靠性较低））。

通过参数：

我说出于维护原因，知道何时以及谁进行了更改非常重要（即使此信息在SCM中也是如此）。

为什么。这些事情对我来说对维护代码都不重要。如果您需要与作者交谈，则从源代码管理中找到此信息相对简单。

由于这个原因，代码具有生命。

历史记录存储在源代码管理中。
您还相信评论是由该人撰写的。How评论会随着时间的流逝而降低，因此这种历史记录变得不可靠。另一方面，源代码管理系统将保持非常准确的历史记录，您可以准确地看到添加/删除注释的时间。

因为没有更改日期，如果不打开SCM工具并搜索较长的对象历史记录，就无法知道何时进行更改。

如果您信任评论中的数据。
这种事情的问题之一是注释相对于代码变得不正确。返回正确的作业工具。源控制系统将正确执行此操作，而无需用户干预。如果您的源代码管理系统很痛苦，那么您可能需要学习如何更适当地使用它（因为该功能通常很容易使用），或者如果不支持它，则可以找到一个更好的源代码控制系统。

因为作者非常重要，所以改变作者比改变作者更可信

所有作者（除了您自己）都是同样可信的。

敏捷性原因，无需打开导航SCM工具

如果您的源代码管理工具繁重，您将不正确地使用它，或者（很可能）您使用了错误的工具集来访问源代码管理系统。

人们会害怕改变某人15年前所做的事情，而不是改变某些事。

如果代码已经使用了15年，那么它可能更坚实，然后只需要6个月而无需审查的代码。随着时间的推移，稳定的代码趋于保持稳定，错误的代码趋向于变得更加复杂（因为存在错误的原因是问题并不像最初想到的那么简单）。

使用源代码控制来获取信息的更多理由。

历史在SCM中

是。最好的理由呢。

开发人员不得直接在代码中了解代码的历史记录

如果我真的需要此信息，我将在源代码管理中查找它。
否则，它是不相关的。

程序包的长度为15,000行，而且结构化的注释很难理解

注释应说明您为什么仍要做某事。
注释应该不被描述代码是如何工作的（除非该算法并不明显）。

我大力支持您的同事。如果您想了解为什么更改了某些内容，除非您在注释中保留了旧代码，否则无论如何都不会不了解SCM。

如果代码太复杂而无法编写大量注释，那么我建议您投入精力进行重构，以使代码可读/可维护而无需大量注释。

毕竟，您聘请程序员，而不是讲故事的人;-)