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

Question

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

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

Answer 1

通常，人们使用内联注释来处理理解代码所必需的事项。例如，如果有一个棘手的算法或微妙的行为，应该在评论中记录下来，这样 reader 可以在查看单个修订版时查看和理解代码。

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

最终的区别在于，在前一种情况下，您希望它在阅读代码时可见，而在后一种情况下，您可以期望有兴趣的人翻阅历史。