如何在Python中编写注释以获得干净和可读的代码

在python中编写良好的注释可以使其他开发人员和测试人员轻松阅读和理解您的代码。

具有一致的语法、描述性变量命名和缩进的整洁代码就像第一本书，更容易理解和维护。

另外，现在，一个人很少编写整个应用程序或软件的完整代码；相反，一个团队或一组人将共同努力实现相同的目标。在这种情况下，清晰易读的代码使协作更简单高效。

开发人员和测试人员始终致力于将无错误的软件部署到生产环境中。编写清晰易读的代码通过使调试更简单和准确加速了这个过程。尽管在生产中可能会发现一些错误，但更清晰的代码更容易更新。

更重要的是，清晰易读的代码寿命更长，因为随着时间的推移，代码始终保持新鲜。

最后，拥有清晰易读的代码对于创建持久性的软件至关重要。但问题是，我们如何确切地实现这一点呢？嗯，一种方法是使用注释。

注释在编程语言中的作用

当你为一个复杂逻辑编写了整个代码，但第二天，当你无法接续以前的工作时，这会令人沮丧吗？当你写注释时，这种情况就不会发生。

注释是用人类语言解释源代码正在做什么。你可以用任何语言编写它们，最好使用英语，因为它是一种全球语言。

因此，无论你在几天甚至几年后回到源代码，注释都会解释给你看你曾经写过的东西。

此外，它们还帮助其他开发人员轻松理解您的代码。这就是为什么带有注释的代码会永远存在，即使没有其作者。

此外，在处理不同的编程语言时很常见发生冲突，特别是在团队中工作时。这就是注释发挥作用的地方。即使你不知道你的队友写的源代码的编程语言，注释也能帮助你理解其背后的逻辑。

代码文档是一种更全面的方式来维护您的源代码，并让您的团队无缝协作。它包含代码的所有内容，如设计、功能、架构、组件等。

注释甚至为此代码文档做出贡献。写得好的注释可以直接纳入代码文档中，以便开发人员不仅能了解代码的目标和原因，还能了解其实现方式。

注释如何提高代码的可读性？

• 注释不仅可以读出代码，还可以帮助您理解每一行代码背后开发人员的意图。因此，如果您将来发现一些错误，就会知道在哪里进行代码更新。
• 您可以将注释作为一个段落来编写，用于解释每个代码块的功能。这样，它们能帮助您和其他开发人员更好地理解代码，提高可读性。
• 注释可以将代码分为逻辑部分，使代码导航更简单。
• 您应该包括详细说明预期的输入、输出和用例，以便测试人员能够阅读您的代码。
• 最后，将写得好的注释放入您的文档中，可以提高代码文档的整体可读性。

如何在python中编写注释？

在python中，注释以井号（#）符号开头。因此，当你以井号（#）开头的行开始时，该行中的任何内容都被视为注释。

当你运行代码时，编译器会忽略以井号（#）开头的行，就像它根本不存在一样。然而，注释仍然在源代码中可见，以达到它们的目的。

python的不同类型注释

有三种主要类型。

#1. 单行注释

这些是你在上面看到的注释。它们以井号（#）符号开头。基本上，以井号（#）符号开头的行是用来写注释的。所以，这被称为单行注释，你只能在以井号（#）开头的一行中写注释。

以下是如何编写单行注释的示例：

# 这是单行注释。

#2. 多行注释

从技术上讲，python不支持多行注释，但在python中有实现这一功能的方法。

你也可以使用井号（#）来编写多行注释。在这里，你写的每一行都应该以井号（#）符号开头。

# 这是第一条注释。
# 这是第二条注释。
# 这是最后一条注释。

#3. python文档字符串

编写多行注释的一种常见方法是使用字符串字面值 – “””….”””。当你在三个引号之间写入内容时，python编译器会忽略这些行并执行文件中的其余部分。

当函数、模块和类后面紧跟着写这些注释时，这些注释被称为文档字符串。

以下是执行此操作的语法：

""" 使用文档字符串编写多行注释
在python中。 """

编写python注释的最佳实践

清晰详细的注释可以提高代码的可读性和可维护性。因此，以下是在python中进行清晰注释的最佳实践。

注释不应该只是描述代码在做什么，而应该反映每一行背后的目的和意图。

删除过时的注释，并确保在修改代码时更新注释。

与其写长篇大论，不如写简短明了、直接点的注释。

不好的例子：该函数以a,b为输入，计算a + b，并返回该值。
好的例子：该函数返回a和b的总和。

为变量和函数命名使用有意义和描述性的名称可以消除冗余的注释。

先写代码？还是先写注释？最佳实践是先写注释，然后写相应的代码。这样，你可以首先思考逻辑，然后将其转换为代码。

# 如果cnt小于1，则返回true。
return cnt < 1

对于整个代码，使用一致的注释格式，如间距、缩进、注释类型等，这样对读者来说更不容易混淆，更有组织性。

使用docstrings来说明python中的函数和类，如下例所示。

def add_num(a,b):
    """ 这个函数返回a和b的和 """
    sum = a+b
    return sum

在你的代码中避免不必要的注释。例如，下面的代码行不需要注释才能理解它。

ans = 42

最佳代码编辑器来管理注释

#1. visual studio code编辑器

visual studio code编辑器是由微软开发的最好的ide，提供完整的开发环境。该工具原生支持node.js和javascript，同时也无缝支持许多其他编程语言。

这个高度可定制的工具有各种扩展功能。”better comments”就是其中一个扩展，它让你创建人性化的注释。

你可以将注释分为警示、查询、突出显示等分类，以便更容易导航。

vs code支持多光标编辑，这样你就可以同时注释或编辑多行。

该编辑器可在mac、windows和linux等所有主要平台上使用。

#2. sublime text

sublime text是大型项目和繁重编码的首选编辑器。该编辑器以其速度、可定制性和快捷方式而闻名。

该工具强大的语法高亮功能帮助你轻松区分代码和注释。

与vs code类似，sublime text也支持多光标编辑，可以同时注释多行。

由于其自动补全功能，你无需手动重复代码行；该功能根据模式自动完成你的代码，帮助你编码更快。

此外，该工具的“goto anything”功能可让你在函数和文件之间无缝切换。

#3. notepad++

nodepad++是一款流行的简单文本编辑器，用c++编写，并支持多种编程语言。它看起来不像vs code或sublime text那样现代化；它的界面非常简单，看起来像它需要的那样。

nodepad++提供了许多标准快捷键，用于有效注释。你还可以自定义快捷键来个性化你的注释体验。

其文档地图功能可显示项目结构的概览，让你无缝导航文件、文件夹和代码。

#4. vim

vim ide提供更快的开发和代码执行。你可以使用键盘快捷键在这个编辑器上完成任何事情，所以你应该认真努力地掌握它。

这个以键盘为中心的编辑器也通过键盘快捷键提供了许多注释功能。它具有强大的功能和命令，可有效地导航注释。

这个轻量级软件可以处理大文件和数百种编程语言。谁不喜欢免费的东西呢？和列表中的所有编辑器一样，vim也是完全免费和开源的。

它在macos和linux系统中本地支持，并可在windows上下载。

#5. pycharm

pycharm是一个专为python开发而设计的强大ide。虽然它支持许多其他编程语言，但它对python最为适用。它具有专为python定制的代码完成功能、语法高亮和调试功能。

此外，它使python中的注释更加高效。它提供导航功能，帮助您轻松跳转到特定的注释。

在pycharm中获取各种注释模板，并高效创建自定义注释模板。

此外，该编辑器的重构工具使您可以轻松更新或修复注释。

结论

在整个代码开发过程中遵循代码规范是必要的，也是编写符合生产要求的代码的必备条件，因为您的代码应该能被所有其他开发人员和测试人员阅读。

创建可读代码的一个重要实践是编写注释。几乎所有编程语言都支持注释。但是，通过本文，您现在应该知道如何编写python注释、它们的类型以及编写注释的最佳实践。

此外，列出了帮助您管理注释的最佳代码编辑器。