您是否更新了错误的古代代码注释?[闭门]

我绝对会纠正不好的评论。

有时只是删除它们,以免误导。

更好的是,我更喜欢重构代码,这样就不需要注释了——自文档化代码比注释更好,因为它 过时了。

Clean Code 我试图将注释转换成函数,将注释代码封装(提取)到一个函数中,这个函数至少和它所替换的注释一样有意义。

如果可以的话,我总是尝试更新它们,或者至少添加一个注释,说明它们可能是错误的。这是一项值得花一点时间的投资。

我经常做的另一件事是添加任何相关的bug编号,以及这些编辑所产生的影响——这对于进一步了解情况总是很有用的。

当我发现GhostDoc生成的无用注释时,我有时会删除它们:

这些评论的目的是什么?

/// <summary>
/// Saves the form properties.
/// </summary>
/// <param name="form">The form.</param>
/// <param name="propertyNames">The property names.</param>
void SaveFormProperties(Form form, string[] propertyNames);

作为一名相当新的程序员,我并没有像自己那样在旧代码上做很多工作,但我会时不时地尝试回去,以确保我自己的评论稍微接近事实。留下没有正确描述代码功能的注释是没有意义的。

如果您的文档是从注释生成的(无论如何,我强烈建议这样做),那么是的,我会将注释与代码保持仔细的同步。

如果发现问题,我会立即修复注释,并且可能会记下改进代码所需的步骤。

然后,如果我有时间,我将整理代码本身(修复它通常需要耗时的回归测试)。如果没有,我会把它留到另一天,但至少我会知道问题是什么,当我有时间回来。

注释对于告诉任何未来的维护人员或程序员代码正在做什么或为什么这样做非常有用。

如果你在不更新注释的情况下修改代码,充其量也会让人感到困惑,甚至会产生误导。

我努力遵守童子军规则,让代码比我发现的更干净。我会更新注释或重构代码,以避免注释的需要。我发现总的来说,完全不发表评论比发表错误的评论要好。

我会修正这些评论。

为什么不尽可能地解决任何问题呢?如果您理解正在处理的代码,那么注释应该是最简单的修复方法。显然,如果您费心钻研,代码应该比您发现的更好。

我甚至认为,在多人接触代码的小组中,注释可以被认为与代码本身一样重要。没有它,思想的交流就会中断。

我总是修正注释——主要是因为我通常是处理一段代码的人。对我来说,这可能是一件类似OCD的事情,但我只是喜欢我正在编写的代码看起来很漂亮——好的变量名、格式(现在在现代IDE中不是问题)和注释。

我不相信代码可以“重构到自文档化的程度”。它可以重构到只需要函数、过程、成员变量、类等的注释,因为每个函数调用只需要1-5行。来自Lisp背景,我喜欢通过分解编程——更简单、可测试、更容易证明正确。

如果项目处于版本控制之下(现在应该是,但你永远不知道),并且有大量过时的评论,我会删除这些评论,并留下一条新的评论,大意是我删除了大量看起来不再有启发性的旧评论,并且我提交了一条注释,说明我已经删除了过时的评论。

最后,我将删除提到删除的注释,或者将其替换为适用于新代码的注释。

然而,在一个由一群程序员维护的系统中,更改旧的、据称毫无意义的注释有一个缺点:

这些评论不再作为评论了! 它们是熟悉代码的程序员的标志。他们是 里程碑式评论 相对于 解释性意见 .

程序员实际上可能在landmark注释中搜索关键字来导航文件。

如果删除landmark注释,甚至更改它们,可能会大大降低使用它们浏览文件的程序员的速度。你把那些与代码有着长期关系的人的心理地图弄得一团糟,这样做弊大于利。大脑是个有趣的东西。在一条时髦的评论中记住一个单词或短语可能比记住一个方法的名称要容易得多。

在我看来,如果注释与代码严重过时,您应该了解原因。假设其他程序员不关心代码似乎是难以置信的假设。也许他们有,也许他们没有。如果你从一个离开的人那里接管了文件,而且你有明确的所有权,那就挖吧!如果你是一群在代码上工作了20年的人中的新人,还有其他证据表明他们

这类似于重新格式化的问题——更改间距、更改开口大括号的位置等等,这在很大程度上取决于所有权。你会在一个文件中的数量是你旁边那个人的20倍吗?还是20分之一的频率?如果是后者,你真的想让他迷失方向吗?

因此,请确保这不是你正在做的,否则明天你可能会听到有人大喊,“那到底是什么功能?”