注释允许您在相关的代码中找到所有更改及其原因,而无需深入研究差异和版本控制系统的复杂性。此外,如果您决定更改版本控制系统,评论将保留。
我参与了一个类似实践的大项目,两次改变了源控制系统。没有一天我不高兴收到这些评论。
这是多余的吗?是。 没必要吗?没有。
当你在代码中时,你需要知道为什么它的结构是这样的,因此在代码注释中。位于代码之外的工具尽管可能很好,但需要在大脑中进行过多的上下文转换才能发挥作用。除此之外,尝试从文档和差异中反向设计代码意图是非常困难的,我宁愿每天阅读一行评论。
当然,我一直认为代码应该受版本控制,而且 的 当前的源代码 强> (你今天可以打开和阅读的那个) 的 应该只在现在时有效 强> 。
如果一个报告在过去和过去一个月中最多可以有3个轴,则更新它以支持最多6个轴无关紧要。只要可以轻松理解当前版本,扩展某些功能或修复一些错误并不重要。修复错误时,只需保留固定代码即可。
但是有一个例外。 的 如果(并且仅当)固定代码看起来不像以前那么不正确;如果你觉得有人可能会在明天来,并且只是通过阅读代码,试图将其改回“似乎更正确” 强> ,那么添加评论是很好的: “这样做是为了避免......等等等等。” 此外,如果背后的问题是团队文化中的臭名昭着的战争故事,或者由于某种原因,错误报告数据库包含有关这部分代码的非常有趣的信息,我不会发现添加不正确 “(参见Bug Id 10005)” 解释评论。
让我想起的是供应商锁定。如果您离开了Rational,则需要确保在迁移期间保留完整的更改历史记录 - 而不仅仅是工件的版本。
在我工作的代码中有一个阶段,早在1994-96时间框架中,有一种趋势是在文件顶部插入更改历史记录注释。这些评论现在毫无意义和无用,我在编辑包含此类评论的文件时执行的许多标准清理之一就是删除它们。
相比之下,在更改位置还有一些带有错误编号的注释,通常解释为什么荒谬的代码是原样的。这些可能非常有用。错误号码可以让你在其他地方寻找信息,并指责罪魁祸首(或受害者 - 它会有所不同)。
另一方面,像这样的项目 - 真实的;上周清理过来 - 让我咬紧牙关。
if (ctab->tarray && ctab->tarray[i]) #ifndef NT prt_theargs(*(ctab->tarray[i])); #else /* Correct the parameter type mismatch in the line above */ prt_theargs(ctab->tarray[i]); #endif /* NT */
NT团队得到了正确的呼叫;为什么他们认为这是一个特定于平台的修复是超出我的。当然,如果代码之前使用的是原型而不是无参数声明,那么Unix团队也必须修复代码。评论是一个帮助 - 向我保证这个错误是真实的 - 但令人生气。
对于我自己,我总是发现这样的评论比它们的价值更麻烦:它们可能导致合并冲突,当你试图隔离两个版本之间的差异时可能会出现'误报',并且可能引用代码更改从那时起,后来的改变已经废弃了。
在不丢失元数据的情况下,通常(并非总是,但经常)可以更改版本控制系统。如果您要将代码移动到系统中 的 不 强> 支持这一点,编写一个脚本以在切换之前将更改历史记录转换为注释并不困难。