记录代码更改

Question

记录代码更改的不同方式有哪些？我目前正在编写代码，这些代码正在经历很多变化。记录代码更改的当前约定如下所示

//Begin add by xxxx for feature/bug xxxx <Date>
........
........
//End add by xxxxx for feature/bug XXXX <Date>

这种草率的评论方式产生了很多混乱。我们通过厚厚的注释寻找实际的代码行。我们不想在版本控制软件的签入注释部分记录更改。我正在考虑在文件的开头维护一个changelog，其中记录了所有的更改。你们用什么方法来记录这些变化？

Answer 1

你会发现，在实践中，重要的信息是代码现在做了什么，而不是它是如何实现的。通过使用这些类型的注释来模糊当前代码，您正在使代码更难阅读和使用。

当您需要返回并查看为什么要执行某些操作时，最好在版本控制中捕获所有信息。不要试图在代码本身中捕获历史。

Answer 2

您的版本控制系统应该是更改信息的主要来源。关于代码中不明显的功能的注释应该以注释的形式记录下来，而不管是出于什么原因，也就是说，它是否是为了更改。

更改代码的程序员，导致更改的相关bug/功能，以及更改的时间，所有这些都已经编码到您的版本控制系统创建的文件的changelog中！任何更多手动添加的changelog，它都将过期，并使文件变得混乱。

Answer 3

我永远不会在代码中做到这一点。永远不会。注释应该是最少的，只是为了让代码中令人困惑的逻辑更清晰(或者，更常见的是，为了指出约定)。始终分别提交每个更改。编写一条简洁的提交消息，最大长度为79个字符。您可以在每个数据包(产品)的根目录中保留一个重新构造的文本-例如CHANGES.rst。这就是我们的做法--你可以看看here。

您还可以使用ticketing/pm系统并在提交消息中提及票证。