你注释源代码的程度如何?

无论您认为代码注释的“完美量”是多少,让我们都同意高质量的注释在开源中非常重要。
265 位读者喜欢这个。
A bunch of question marks

Opensource.com

虽然最好的代码可能是自文档化的,但即使是最清晰的代码也需要充分的文档,以便人类读者能够快速解析和理解。

但在实践中,在哪里以及注释多少内容更多取决于个人开发人员的决定,而不是代码本身的元素。编译器或解释器通常不关心您的注释;毕竟,它们不是为它准备的,而是为我们人类准备的。因此,虽然一些组织和项目会提供指南,但注释风格更开放给解释。

一般来说,您的注释清晰简洁会受到赞赏。但特别是在开源中,您不能想当然地认为查看您代码的其他开发人员熟悉编写代码的上下文。每个人在某个时候都是项目的新手,您不能指望他们了解项目的历史、怪癖或它使用的库。新的贡献者也可能不是您语言的母语人士。

因此,编写良好且位置恰当的注释是项目文档的重要组成部分。您是否确保您的项目代码尽可能易于访问?

您多久注释一次?您认为您的注释频率足够吗?请告诉我们您的想法!

标签
User profile image.
Jason 在 2013 年至 2022 年期间是 Opensource.com 的工作人员和红帽员工。此个人资料包含他当时与工作相关的文章。其他贡献可以在他的个人帐户中找到。

9 条评论

我通常在编码之前进行注释。这使我能够遵循清晰简洁的思路模式。我将其作为伪代码的一部分。我发现,花 30 分钟写下我希望代码做什么,可以节省我数小时对着键盘猛敲,试图从困境中编写代码。清楚地了解您要去哪里只能提前完成。

真正的程序员不写注释 - 代码是显而易见的。 ;-)

嗯,说实话,我倾向于使用无实现的注释作为 *Doc 样式,即 /** .... */,并将注释一些使用 /* ... /* 实现的“特殊事物”。

“给我看你的流程图并隐藏你的表格,我会继续感到困惑。给我看你的表格,我通常不需要你的流程图;它们会很明显。” Fred Brooks,《人月神话》

代码告诉你怎么做。注释告诉你为什么。也就是说,它们告诉你代码正在对你的数据结构(表格)进行的更改。

回复 作者:Jukka (未验证)

这项调查的问题在于,通常适用多个答案。例如,对我来说,“几乎没有”与“我认为我已经找到了最佳点”相同。

听着,如果你编写混乱的代码,再多的解释也无法使其清晰,如果你的代码混乱,那么你的解释也可能如此。此外,对代码的评论永远不会检查正确性,并且很少更新。

如果你编写清晰的代码,人们只需阅读它就可以看到你做了什么,无需解释。有时,像 Hilliard 先生一样,我在代码之前编写注释来记录过程的步骤,但我已经多年没有编写伪代码了。

问题是,所有代码都会告诉读者事情是什么以及如何完成的。如果你已经做了一段时间,而我已经做了很长时间,你通常可以进入编写它的人的脑海,并经常弄清楚他们为什么这样做,但这很高级。因此,注释应该侧重于你为什么要做你正在做的事情。

为了使您的代码更易于理解,您应该像 Perlis 博士所说的那样,在编写代码时建立并遵循惯用语。这将更有助于您的读者理解正在发生的事情。

这里有一些有趣的评论。我尝试注释大多数行,我认为我可以忽略 'Else' 和 'EndIf' 行。这并不是为了帮助别人,而是为了提醒自己我在做什么。我通过这样做发现了许多错误,或者可能简化代码的情况。我推荐这样做,您可能会惊讶于您的发现。

YMMV(差异很大),但通常我将注释保留用于更高级别的内容。例如,我更喜欢注释函数规范(对于你们 C 程序员来说是原型 :-)),以便查看我的代码的人知道函数/方法*做什么*。此外,我通常在我的包的头部添加注释,以便人们知道该包的职责是什么。我在实际代码中添加注释是非常非常罕见的,除非我正在使用具有非显而易见操作的非常复杂的算法。我更喜欢给出长而描述性的名称,而不是求助于注释。例如,如果你看到

function Exist_Device(Serial_Number : Integer) return Boolean
is
begin
for I in Device_Table.Range loop
if Device_Table(I).Serial = Serial_Number then
return True;
end if;
end loop;

return False;
end Exist_Device;

很清楚它做什么,无需注释。

作为一名从事维护编程数十年,并花费一生时间查看他人代码的人,我通常做的第一件事是删除注释。它们是非功能的,因此无法保证它们与实际运行的代码有任何关系。它们可能曾经有关,但代码可能已更改,并且注释不再正确。

你无法知道,所以你无法信任它们。删除它们,使实际代码不那么混乱,然后努力理解实际代码。然后使用它。

因此,如果像我这样经验丰富的维护程序员特意忽略您的注释,那么它们实际上增加了多少价值?

我做的恰恰相反,我发现有人没有注释它,我正在添加一些,因为我想确保以后的人不必浪费时间弄清楚某些东西的作用。

如果注释毫无意义,是的,我会删除它,但我赞成人们“展示他们的工作”,以便另一个开发人员可以理解它。

回复 作者:David Barrett (未验证)

我总是记录我的代码,即使它有意义。我这样做是因为这是一个好习惯,我可以为任何需要使用它的人制作文档。

我知道开发人员之间关于是否应该记录文档可能会变得激烈,我知道我的团队对此存在分歧。

Creative Commons License本作品根据 Creative Commons Attribution-Share Alike 4.0 International License 获得许可。
© . All rights reserved.