在代码中编写更好的注释的 5 个技巧

帮助其他人更轻松地遵循您的代码

作为程序员或技术领域的一员，我们经常需要定期阅读、分析和编写代码。有些代码比其他代码更容易编写和遵循。代码越清晰，理解、使用和构建的速度就越快。编写好代码的能力是任何程序员或数据科学家的基本技能。

但是，其他重要的技能之一是写好评论。现在，我知道如果你掌握了编写可读代码的艺术，那么你就可以少写注释，但我们永远不能完全停止写注释以求现实。所以，即使你擅长写代码，你也需要能够写出好的注释。

注释是每个好代码的主要部分。如果您打开一个代码并且它没有任何注释，那么阅读和理解该代码将非常耗时。缺乏评论与使用大量评论同样糟糕。如果你的代码文件有 50% 或更多的注释，那么你的代码可能写得不是很好，因此你需要很多注释来解释它。

写好评论不是一件难事；这只是一个需要大量练习的。幸运的是，如果您正在阅读本文，那么您要么是程序员、数据科学家，要么是在技术领域工作。这意味着您需要在职业生涯中编写/阅读大量代码。

那么，如何写出好的评论呢？在本文中，我将介绍 5 个技巧，以帮助您撰写更好的评论并将您的评论写作技巧提升到一个新的水平。

说到写评论，我想说，少即是多。尽量不要过度解释代码的每一步。保持你的评论简短，类和函数在 3 句话以内，内嵌评论在 1 句以内。如果你的代码写得很好，你不需要很多注释来解释它。您只需要向用户（程序员同事）提示您做出某些决定的原因以及不同代码部分的整体功能。

作为一般规则，为了让编程社区保持有序和统一的数量，在为一个类编写注释（文档字符串）时，包括一个简短的描述和最后一次修改的日期。但是，当您为函数编写一个时，它必须包含对其用途、参数和结果的描述。

通常，代码被分为卡盘、函数、类、模块、库等。每一个都可以被认为是代码的一个级别。因此，当您编写注释时，最好为每个级别开发一种特定的样式并在您的代码中维护它。

因此，您将对所有代码函数使用相同的文档字符串编写风格；您的函数和内嵌注释也是如此。这将帮助任何阅读代码的人快速浏览并理解其结构，甚至无需深入阅读。

初学者在第一次学习编码时犯的最大错误之一——我也这样做过——是首先编写代码，然后检查代码并写注释。这种方法的问题在于，编写代码通常需要几天甚至几个月的时间。因此，当我们接近撰写评论的步骤时，我们已经忘记了我们做出某些决定的原因。

在这种情况下，最好的办法是在编写代码时写注释。一些程序员甚至可能会说您应该在编写代码之前编写注释（它将作为您的指南）。但是，在我看来，并行移动代码和注释是最省时省力的方法。因此，边写边写评论，最后根据需要进行编辑。

评论不仅适用于将来会阅读您的代码的人；它们也适用于未来的您，您将在接下来的开发步骤中对其进行维护和扩展。因此，明确您的评论将有助于其他开发人员和您自己。

“只要在屏幕上放置一行代码，您就处于该代码的维护模式。” — 菲尔·哈克[0]

最后，也许是最直接的提示，就是让事情保持简单。保持您的代码简单，这样就不需要在评论中进行大量解释，同时保持您的评论简单明了，以便其他人和将来您会发现它们很容易理解。

基本的编程原则之一是让你的代码自己说话。尽管这一运动最初是由不喜欢写评论的程序员发起的——通常，他们中的大多数，你不能 100% 消除评论。不过，您可以显着减少它们的数量，但编写更简单的代码。

成为一名成功的数据科学家需要您掌握不同的技能；编程可能是这些技能列表的首位。成为一名优秀的程序员意味着您可以编写清晰易读的代码和简洁明了的注释。两者对于生成高质量代码同样重要。然而，大多数人更多地专注于开发他们的代码编写技能，而忽视了他们的评论编写技能。

像任何其他技能一样，要想更好地写评论，唯一的方法就是练习写更好的评论。首先，阅读您认为写得很好的评论，并反思您喜欢它们的原因。通常，简短、清晰、描述性和不过度使用的评论是最理想的。

本文介绍了 5 个技巧，这些技巧将使您的评论写作技巧更上一层楼。我把这个留给你；注释并不意味着向用户解释代码；相反，您的代码用于向计算机解释注释。

文章出处登录后可见！

已经登录？立即刷新