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

无论你认为代码注释的“完美量”是多少，让我们同意高质量的注释在开源中非常重要。
265 位读者喜欢这篇文章。
A bunch of question marks
图片来源

Opensource.com

总共 558 票
几乎每一行。
4% (25 票)
比我认为需要的更多。
13% (70 票)
我认为我找到了最佳点。
32% (178 票)
比我认为应该的要少。
35% (194 票)
几乎没有。
16% (91 票)

你多久注释一次代码？

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

编程和开发

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

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

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

你多久注释一次？你认为你注释得足够频繁吗？请告诉我们你的想法！

标签
投票
编程
Jason B
User profile image.
Jason 是 Opensource.com 的员工和红帽员工，从 2013 年到 2022 年。此个人资料包含他在此期间与工作相关的文章。其他贡献可以在他的个人帐户中找到。
更多关于我

9 条评论

Avatar
Cory Hilliard | 2017 年 10 月 27 日
还没有读者喜欢这条评论。

我通常在编码之前进行注释。这使我可以遵循清晰简洁的思路。我将其作为伪代码的一部分。我发现，花 30 分钟写下我希望代码执行的操作，可以节省我几个小时对着键盘猛敲，试图从困境中编写代码。预先清楚地了解你的目标是唯一的方法。

Avatar
Jukka | 2017 年 10 月 27 日
还没有读者喜欢这条评论。

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

好吧，老实说，我倾向于使用不包含实现的注释，如 *Doc 样式，即 /** .... */，并将使用 /* ... /* 注释一些“特殊的东西”。

Avatar
Shawn H Corey | 2017 年 10 月 27 日
还没有读者喜欢这条评论。

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

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

Avatar
Jonathan Guthrie | 2017 年 10 月 27 日
还没有读者喜欢这条评论。

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

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

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

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

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

Avatar
Charlie | 2017 年 10 月 28 日
还没有读者喜欢这条评论。

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

Avatar
Riccardo | 2017 年 10 月 31 日
还没有读者喜欢这条评论。

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;

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

Avatar
David Barrett | 2017 年 10 月 31 日
还没有读者喜欢这条评论。

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

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

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

Avatar
Ed | 2017 年 12 月 9 日
还没有读者喜欢这条评论。

我做的恰恰相反，我发现有人没有注释，我会添加一些，因为我想确保以后有人不必浪费时间弄清楚某些东西是做什么的。

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

Avatar
Ed | 2017 年 12 月 9 日
还没有读者喜欢这条评论。

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

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

相关内容

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