维护评论答案

【问题标题】：Maintenance commenting维护评论
【发布时间】：2010-10-04 18:02:26
【问题描述】：

您在修改现有代码时使用了哪些特殊技术？

例如：假设您在方法中修改了业务规则。你用特殊的 cmets 标记修改的部分吗？

您在修改代码时使用的任何编码/注释标准？

【问题讨论】：

【解决方案1】：

你的意思是这样的：

foo();  // changed by SecretWiz, 20090131

我不会推荐这个。它使代码文件混乱，版本控制系统应该为您处理。它会跟踪谁更改了什么。使用

svn blame

【讨论】：

确实，这也让我发疯了。
当您处理其他人以这种方式装饰的文件时，您是否会删除类似的内容？
或者如果你心情好，使用svn praise代替（做同样的事情）:)

【解决方案2】：

如果我做一些事情，比如修复一个相对晦涩的错误，基本上是任何不太明显的事情，我为什么要按我的方式编写代码，我通常会添加注释来解释它，以便我（或某人否则，如果其他人曾经修改过我的代码 ;-) 以后不会意外删除它。

【讨论】：

【解决方案3】：

我总是尝试做的一件事是在我为该更改所做的代码签入 cmets 中的错误跟踪系统中输入错误 ID（或功能请求 ID）。我添加了类似“有关更多详细信息，请参阅 bugzilla 中此错误/功能的 cmets”之类的内容。在那里，我可以并且通常可以解释该代码更改的基本原理。这意味着所有更改或至少所有重要更改都需要通过功能请求/错误 ID 进行跟踪。我多次创建错误只是为了详细解释所涉及的业务原因。

【讨论】：

【解决方案4】：

不，这是一个非常糟糕的主意。您的源代码管理会保留所有编辑的历史记录。如果您想要其他东西，请在您的错误跟踪工具中输入。无需注释掉旧代码部分或在其中乱扔以下内容：

// modified by A.B. on 11/23/99 to fix issue #123456

我已经在我们的代码库中看到过这样的 cmets，但多年后它们毫无意义。 A.B.到底是谁，问题#123456是什么？如果代码仍然存在，这是否意味着有人计划在未来回滚这些更改？

这些 cmets 没有任何价值，只会让您的代码变得混乱。

【讨论】：

我认为提到问题#还不错。我们经常遇到这样一种情况，即某些单行更改的理由可能很复杂，并且问题跟踪器中的讨论太长而无法复制粘贴到代码中（现在会弄乱它）。因为问题跟踪器——比如版本控制——不会去任何地方，我发现添加参考是可以的。即使多年后，您仍会看到导致特定代码行的完整讨论。

【解决方案5】：

我建议创建一个方法并从正在修改的代码中调用它。
此外，命名方法以暗示方法的目的/意图。

例如GiveRebateIfValidCoupon();

【讨论】：

【解决方案6】：

“您在修改代码时使用的任何编码/注释标准？”

是的。创建新的子类。保留旧代码，除非在极少数情况下您没有正确测试它并且实际上是错误的。

需求的改变意味着添加子类和新的测试来处理新的业务规则。

【讨论】：

有趣的想法，但我不知道它是否适用于所有情况。有时业务规则会永远改变，没有必要保留这些旧代码。
这听起来像是一个僵化的秘诀
我在这里闻到了一些类似 C++ 的技术吗？如果你坚持在我的 C#/java 项目上那样工作，我会让你被踢出项目。 -1 来自我。

【解决方案7】：

我添加特殊 cmets 的唯一情况是修改是临时的。在那种情况下，我用一个标准关键字（例如，TEMPFIX）标记它，以便我以后可以找到它。当然，您必须记得返回并删除代码或进行永久性更改，但在某些项目中，我们强制使用允许我们指定代码停止编译的到期日期的宏。

除此之外，我们依赖源代码控制。

【讨论】：

【解决方案8】：

代码应符合您或您的组织拥有的任何编码标准。

所以，不，不应该有任何代码被修改过的特殊 cmets - 所有或至少大部分代码迟早会被修改。

如果您继承的代码不符合注释标准，那么请务必将 cmets 添加为 refactor 代码。如果代码真的很旧并且没有文档，那自然意味着添加文档。

在修改代码之前理解代码是件好事（顺便说一下）。

【讨论】：

【解决方案9】：

通常我只会更改代码并让我的 cmets 在我的源代码管理中签入。在选择的任务跟踪工具中，您可以参考实现任务的版本。

有时我知道某些功能会来回更改、移动、更改名称等，具体取决于讨论用户需求的方式。在这种特殊情况下，我会将旧版本保留在那里，然后将其注释掉。然后，稍后取消注释就变得微不足道，而不是通过源代码控制寻找旧版本。如果他们以后必须维护您的代码，这也可以节省一些人的麻烦，因为当用户再次改变主意时，该要求已经在代码中，等待取消注释。

【讨论】：

【解决方案10】：

我必须同意这里的许多其他人的观点。 “如果您的代码中不需要某些内容，请将其删除”。尤其是在生产代码中，您最不想要的就是很多混乱。与阅读您的维护评论并可能会感到困惑相比，某人可能更容易弄清楚您的更改是如何工作的。

我曾经在我的项目中保留旧的弃用代码，但随着时间的推移，一个本应只有几千行的项目最终超过了 10,000 行，并且难以管理。

【讨论】：