评论是否被视为文件形式？

当我为自己编写小型脚本时，我会将代码和注释高度堆积在一起（有时注释比代码更多）。我要说的很多人都说，即使这些脚本是个人的，我也应该记录这些脚本，以便如果我确实出售它们，我将做好准备。但是注释不是文档形式吗？

这不是吗：

$foo = "bar"; # this is a comment
print $foo; # this prints "bar"

被视为文档，特别是如果开发人员正在使用我的代码？还是认为文档不在代码本身之外？

注释绝对是文档。对于大多数项目，（不幸的是）注释是项目文档的主要（但不仅是）形式。因此，正确处理非常重要。您需要确保即使更改了代码，该文档仍然准确无误。这是带有注释的常见问题。开发人员在使用熟悉的代码工作时经常“调优”它们，因此他们忘记更新注释以反映代码。这可能会创建过时且令人误解的评论。

许多人建议使代码自记录。这意味着您可以对代码进行重组，以取代注释，而不需要注释。这可以消除大多数“什么”和“如何”注释，但是对于“为什么”注释并没有真正的帮助。尽管这可能有效地消除了大多数注释，但是仍然有很多时候编写注释是记录一段代码的最简单，最有效的方法。

它们是文档的一种形式，但是请记住，文档是情人眼中的……。

• 对于某些人来说，自我记录代码就足够了。但这假设客户具有一定的技术细节。我们应该谨慎地认为这已经足够，因为我们的自我可能会告诉我们“很明显，这段代码在做什么”，但是时间可以证明是相反的。它还假定您已预先了解读者的技能。

• 对于那些只看源代码但技术专业知识较少的人，可以使用注释。但这假设有人正在查看源代码。

• 如果您是技术人员，但是缺乏阅读所有源代码的时间，则可能需要技术手册。

• 如果用户缺乏技术技能，但只需要知道发生了什么，则需要用户文档。

因此，真正的问题是谁是您的客户？如果是这样，那么自我记录代码或注释就足够了。如果是给其他人的，您可能想扩展文档的方式。

是的，评论是一种文档形式。对于必须维护或更新您的代码的人来说，它们是否有用的文档尚待解决。

我知道您的意思只是举个例子，但是类似

print $foo; # this prints "bar"

没有用 它只会增加视觉混乱。不要记录明显的东西。

在方法或函数定义的开头的块注释，描述函数或方法的目的（高级术语），输入，输出，返回值（如果有的话），异常（如果有的话），前置条件和后置条件是有用的，但只能达到他们告诉某人应该如何使用该函数或方法的程度。他们没有解释功能为何存在。

如果其他人需要维护您的代码，则需要在某处记录需求和设计，而这通常不在源代码本身中完成。

我发现坚持使用“干净代码”中的Bob Martin的方法通常可以解决以下问题：您认为自己是在评论过多还是在评论不足，而忽略了文档：

我们是作者。关于作者的一件事是他们拥有读者。确实，作者有责任与读者保持良好的沟通。下次您编写一行代码时，请记住您是一位作者，是为会判断您的努力的读者写的。

...阅读与写作所花费的时间比例远超过10：1。作为编写新代码的一部分，我们不断阅读旧代码。

因此，换句话说，没有文档，您的代码是否可以自我解释？没有固定的规则（除非您为可公开访问文档的Microsoft之类的公司工作），很大程度上取决于帮助将来经常使用您的代码的读者。

文档应该记录为什么不怎样。该如何应该是不言自明的代码，也就是除非是一些神秘的优化技巧或其他语言的特定技术，不常用存在的。

该为什么可能不应该在代码中，它应该是别的地方像一个产品积压，这是依赖于犯了可以在更改日志或分支机构的名称来搜索故事IDS意见。

注释是一种文档形式。劣等形式，建议您已找到可以更好地分解代码的区域。

听起来您像在强迫性地评论事物。有其他选择可能是一件好事。我可以想到三种高级的文档形式：

1）更好地分解代码。不用添加注释，而是提取名称为您要编写的注释文本的方法或函数。因此，代码说明了您要发表的评论。

2）测试。这是我通常会搜索出的文档形式。单元测试和验收测试是实时文档，如果使用很多有意义的方法来表达意图，则可以轻松阅读，如第1点所述。

3）对于脚本，--help选项。这是您可以修改文档的地方。坚持示例，预测用户的需求。

总之，如果您发现自己倾向于发表评论，请检查是否可以通过更好地构建代码来与读者交流。还是有一个测试来传达为什么存在该代码？如果您仍然想发表评论，请承认失败并这样做。