有用和无用的代码评论

2021-06-18 08:56:03

不幸的是,许多评论并不是特别有用。最常见的原因是评论重复代码:可以轻松地从评论旁边的代码中轻松推断出评论中的所有信息。

//添加水平滚动Barhscrollbar = new jscrollbar(滚动条,水平);添加(hscrollbar,borderlayout.south); //添加一个垂直滚动arbvscrollbar = new jscrollbar(jscrollbar.vertical);添加(vscrollbar,borderlayout.east); //初始化标签位置相关的valeScaretx = 0; carety = 0; caretmemx = null;

反对评论的论点是它们与代码本身“处于相同的细节级别”。该代码在其目的中清楚,因此评论是冗余的。

John继续说明,有用,评论应该提供从代码中没有推动的级别细节:

评论通过提供不同级别的详细信息来增加代码。一些评论提供比代码更低,更详细的级别的信息;这些评论通过澄清代码的确切含​​义来添加精度。其他评论提供比代码更高,更摘要,更高的信息;这些评论提供直觉,例如代码背后的推理,或者更简单,更抽象的思考代码。

我认为这是一个非常公平的和理由的解释,在代码中有用或没有。

如果有人说评论不增加任何价值,我会问:对谁?

就个人而言,我从来没有喜欢写出明显评论的建议是不好的实践 - 可能是因为我一直在写出明显的评论。

评论与代码相同的详细信息,因为代码可能对您作为一个流利的读者和代码作家有用,但他们是像我这样的人仍然弄清楚如何阅读和写作代码。我发现它们是有用的,因为我写代码,因为他们允许我陈述我的意图(以简单的英语)翻译成代码,然后比较陈述,看看我达到了目标。

如果您与一支人团队合作,那么您必须弄清楚如何将代码写在一起。这可能意味着妥协和削减对您有帮助的评论,但对他人分散注意力(在您在编写代码的过程结束时,您总是这样做。

也许这是一个明显的陈述,但如果写作“无用”的代码评论有助于你,那么他们并没有用。他们对面:有用。

它让我想起了我学过西班牙语的时候。人们总是说,“不要为你的头脑中的单词做翻译。让这些话意味着他们在自然语言中的意思。“然而,当我第一次学习语言时,这正是我会做的:

最终我变得有流利的地方,在我不需要在我脑海中进行这款手册,逐步,逐行的翻译。单词以自己的语言有自己的意义。在那一点,我意识到它是无用的(对我来说)翻译成英语。

//你的名字是什么?¿como te llamas?//我的名字是jimme llamo jim.//图书馆在哪里?¿donde esta la biblioteca?

鉴于人们对代码评论的说法,您可能认为这样的评论是无用的。来自约翰的书:

可以通过查看评论旁边的代码来看,从未见过代码的人可以通过查看评论旁边的代码吗?如果答案是肯定的...那么评论并不是更容易理解的代码。

这些评论有助于代码更容易理解吗?好吧,这取决于你问谁。

说代码评论是没用的是我们作为守则的流利读者的判决。它无视价值评论对某人比自己读写或写作代码的人更流利的评论。

如果你不认为自己流利,你可能会从评论中获得大量的价值,因为他们可以帮助你翻译你的东西和#39;重复熟悉另一种语言 - 进入你所在的东西 - 例如,英语。

当他们被写入时,评论可以提供一种非常不同的目的。那些几乎是两种不同的活动。

所以当有人称之为特定的代码风格,评论没用,问问自己:对谁?授予,您必须介意代码,您为人群贡献,特别是对个人项目:如果特定类型的代码评论很有用,请继续执行此操作。