将错误编号放在源文件开头的注释中的好主意？[关闭]

将错误号放在文件本身的标题注释中是一种好习惯吗？

评论看起来像这样：

 MODIFIED    (MM/DD/YY)
 abc 01/21/14 - Bug 17452317 - npe in drill across in dashboard edit mode

 cde 01/17/14 - Bug 2314558  - some other error description

似乎有帮助，但是否认为这是不好的做法？

我以前见过这种情况，既可以由作者手动完成，也可以由与版本控制系统集成的脚本和触发器自动完成，以将作者，签到注释和日期信息添加到文件中。

我认为这两种方法都非常糟糕，主要有两个原因。首先，它给文件增加了混乱和噪音，尤其是当这些注释老化并且变得与文件的当前状态无关时。其次，它是来自版本控制系统中已经维护的内容的重复信息，如果您使用的是支持变更集的现代版本控制系统，那么实际上它会丢失有关变更的信息。

如果有的话，请考虑与缺陷跟踪系统集成。某些工具允许您将签入注释中的缺陷或任务ID号链接到跟踪工具中的项目。如果工具中包含所有缺陷，增强功能要求和工作任务，则可以这种方式提供链接。当然，这带来了对项目中那些工具的依赖的不利影响。

在一种情况下，我会执行此操作，即作为对未来程序员的警告的一部分：“请勿foo()在此处直接调用函数；这已导致错误＃1234，即...”，然后对此进行了简短说明错误如下。

如果代码已更改为没有诱惑可以foo()直接调用的方式，请删除该注释。这只会激怒并炸毁代码。

这是完全可怕的做法。为了实现纯粹的复制效果，需要付出更多的努力。换句话说，仅使用提交日志添加的唯一内容就是可能产生不一致。您的源文件中杂乱无章，您永远都不会看。

我唯一可以看出的缺点是，您无需访问版本控制即可重构源历史记录，例如在研究打印输出时。但是很少有人能胜任复杂的软件开发工作，同时又无法理解版本控制。

没有。

这就是人们在使用版本控制系统之前所做的事情（即，当源代码只是zip文件中的备份时）。

恕我直言，这是一个非常糟糕的主意。在版本号100之后，您将拥有90％的注释和10％的代码。我认为这不是干净易读的。

我看到的唯一一点是，当您必须在SCC之间交换代码，并且无论出于何种原因，都无法在两个系统之间传输历史记录时（但是即使以这种方式保存了历史记录注释，您也会失去diff历史记录同样，因此保存评论只会对您有所帮助。

我看到每个人都反对这个想法，并给出了人们为什么这样做的历史原因（源代码控制前的时代）。

但是，在我目前的公司中，数据库开发人员正在遵循这种做法，并且他们还在代码段周围标记了错误号。当您在代码中看到错误时，有时我会发现这很有用，您可以立即找出导致此问题的错误修复。如果我们的数据库包中没有这些信息，那么要找到实现该问题的根本原因肯定不容易。

是的，它使代码混乱，但有助于找到该段代码存在的原因。

乔尔测试的要点之一是

您有错误数据库吗？

如果您认为这些信息很重要，则可以将其保留在错误数据库中，但是它们只会在注释中产生干扰。

我认为您在这里有两个问题。首先，当大多数系统允许您输入修订注释时，为什么您应该纯粹依靠差异？就像好的代码注释一样，您会发现做出更改的原因，而不仅仅是更改本身。

其次，如果您具有此功能，请将其全部放在同一位置是一个好习惯。无需遍历文件即可找到不再需要的标出的代码行。工作代码中的注释可以告诉您为什么使用这种方式进行编码。

一旦将其付诸实践，所养成的习惯就使每个人都更容易使用代码库。

相关的错误和功能跟踪以及更改此文件的原因，可以使您了解需要深入了解历史记录并可能查看差异的深度。我要求“更改回原始公式”。我知道在修订历史记录中可以找到的位置，只检查了一个或两个差异。

就个人而言，标记出来的代码看起来像是正在通过反复试验解决的问题进行的工作。从生产代码中消除混乱。能够轻松滑入和滑出代码行只会使其更容易混淆。

如果您没有带有提交消息的VCS，也没有bug跟踪系统，但可以选择留下评论，则跟踪更改是一个选择，而不是最佳选择。
最好有一个包含该信息的电子表格，或者如果您所在的环境中没有此类“奢侈品”，则在您的源附近放置一个文本文件。
但我强烈建议您，如果您处于这种环境中，就开始着手投资VCS和错误跟踪系统：)

请记住这一点-代码通常比支持它的工具更长。换句话说，问题跟踪器，版本控制和所有其他脚本将在开发过程中发展。信息丢失。

尽管我确实同意，但文件混乱却很烦人，打开文件并了解其历史记录而无需使用工具，这一直非常有帮助-特别是在维护代码的情况下。

就我个人而言，我认为工具和代码内日志都有空间。

我知道的Git不这样做，简单的答案是“为什么地球上会是去那里？”

通常，这是一种模块化程度较低的设计。在这种解决方案下，现在文件是内容和元数据之间的某种混合。Amazon S3是用于存储文件的服务的另一个示例，该服务不会在文件中添加YAML开头或类似内容。

文件的任何使用者都必须先通过版本控制系统对其进行处理。这是紧密的耦合，例如，如果您不喜欢的IDE不支持VCS，则会破坏它。

不，在代码中以注释的形式跟踪错误修复不是一个好习惯。这只会产生混乱。

对于您提到的版权信息，我也会说同样的话。如果公司外部没有人会看到此代码，则没有理由包括版权信息。

如果您使用的是版本跟踪软件（Git，SVN等），则应在提交消息中包括这些注释。没有人想挖掘每个代码文件的头来生成发行说明或查看所做更改的概述。这些更改日志应全部存储在版本跟踪历史记录和/或缺陷跟踪器中，或同时存储在两者中。

如果您希望对此主题有个很好的阅读，我建议您使用Clean Code的第四章。

我认为此讨论中的其他元素通常被遗忘，但有些情况下某些修订意见对团队来说是迅速的。

当在具有共享代码库的团队环境中工作并且几个团队成员可能在同一代码区域中工作时，在正确的范围（方法或类）中放置简短的修订注释以指示进行了更改，这对快速解决合并或签入冲突。

同样，在涉及多个（功能）分支的环境中工作时，第三方（构建主文件）可以更轻松地确定解决潜在冲突的方法。

每当您必须离开IDE并询问某人为何更改某些内容时，这都会破坏团队成员的工作效率。在正确的范围内快速注释可以帮助减轻或消除大部分此类干扰。

当整个更改的完整性被后续修复程序修改时，与代码段直接相关的任何错误信息都将变得无关紧要。

当我们不得不依靠外部工具（例如javadocs）从代码创建发行说明时，通常在功能摘要中添加信息。对于现代版本控制工具，它通常是无用的或多余的。

如果人们不得不诉诸于一些晦涩的或非恒星的代码，那么将来的开发人员可能会尝试更改它们，而不知道其背后的原因，就像在变通解决方案中那样，那么，仅作为一段非常模块化的代码中的注释才有意义。库错误/缺点。

我绝对不会将此类信息放在文件的开头-通常这类事情属于票务系统。

但是，在某些情况下，对票证系统和/或其他文档的引用是有意义的。例如，如果有冗长的设计说明或替代说明。或提供有关如何测试事物的信息，或提供解释说明为何如此进行的信息。如果很短，则它属于文件本身；如果它很长和/或大约是一个较大的图片，则可能需要将其放在其他位置并进行引用。

我目前在工作中分配给的项目在每个文件的开头都有这种类型的错误编号列表。但是，没有任何开发人员仍在该项目上追加任何内容。他们中的大多数人认为这是对空间的无用浪费，因为它远不及使用我们的版本控制系统来跟踪对文件的错误提交。

在某些经过重大修复和增强的关键文件中，这些列表非常大，您必须滚动浏览它们才能获得代码。当使用这些列表时，可能会导致一些误报，因为每个列表都列出了简短的错误标题或简短说明。

简而言之，这些列表充其量是没有用的，更糟糕​​的是，它们会浪费大量的空间，这使代码更难于搜索和定位。