我应该在提交消息或内联注释中写下推理吗？

Question

我经常听说提交消息应该描述我进行这些更改的原因。我想我同意这一点。然而，我也经常听说内联注释（即源代码中的注释）应该说明代码为什么以这种特定方式工作，而不是它的作用。

那么，什么时候应该将推理放入提交消息中，什么时候应该将其写在内联注释中呢？是否有一些可以应用的经验法则或最佳实践？

Answer 1

通常，人们会使用内联注释来表达理解代码所必需的内容。例如，如果存在棘手的算法或微妙的行为，则应将其记录在注释中，以便读者在查看单个修订版时可以查看并理解代码。

您将使用提交消息来解释进行更改的理由，包括为什么选择一种替代方案而不是另一种方案。例如，如果您选择了一种算法而不是另一种算法（例如，出于性能原因），则该算法属于提交消息。您还应该记录诸如引发变革的问题或想法等内容，以帮助向未来的读者解释为什么您的变革是有价值的。

最终的区别在于，在前一种情况下，您希望它在阅读代码时可见，而在后一种情况下，您可以期望感兴趣的各方查看历史记录。