如何在Python3中编写注释

介绍

注释是存在于计算机程序中被编译器和解释器忽略的行。在程序中使用注释可以使代码对人类更具可读性，因为它提供了一些关于程序每个部分正在做什么的信息或解释。

根据您的程序的目的，注释可以作为您自己的注释或提醒，或者可以编写它们以使其他程序员能够理解您的代码在做什么。

一般来说，在编写或更新程序时写注释是个好主意，因为以后很容易忘记你的思考过程，而且从长远来看，以后写的注释可能不太有用。

先决条件

您应该在您的计算机或服务器上安装 Python 3 并设置编程环境。如果您没有设置编程环境，您可以参考本地编程环境或服务器上的编程环境适合您的操作的安装和设置指南系统（Ubuntu、CentOS、Debian 等）

注释语法

Python 中的注释以井号 (#) 和空格字符开头，一直到行尾。

Info: 要跟随本教程中的示例代码，请通过运行 python3 命令在本地系统上打开 Python 交互式 shell。然后，您可以通过在 >>> 提示符后添加示例来复制、粘贴或编辑示例。

通常，注释看起来像这样：

# This is a comment

因为注释不执行，所以当你运行一个程序时，你不会在那里看到任何注释指示。注释在源代码中供人类阅读，而不是供计算机执行。

在“你好，世界！” 程序，注释可能如下所示：

你好.py

# Print “Hello, World!” to console
print("Hello, World!")

在迭代 list 的 for 循环中，注释可能如下所示：

鲨鱼.py

# Define sharks variable as a list of strings
sharks = ['hammerhead', 'great white', 'dogfish', 'frilled', 'bullhead', 'requiem']

# For loop that iterates over sharks list and prints each string item
for shark in sharks:
   print(shark)

注释的缩进级别应与它所注释的代码相同。也就是说，没有缩进的函数定义将有一个没有缩进的注释，并且后面的每个缩进级别都会有与其正在注释的代码对齐的注释。

例如，下面是注释 How To Make a Simple Calculator Program in Python 3 教程中的 again() 函数的注释，代码的每个缩进级别后面都有注释：

计算器.py

...
# Define again() function to ask user if they want to use the calculator again
def again():

    # Take input from user
    calc_again = input('''
Do you want to calculate again?
Please type Y for YES or N for NO.
''')

    # If user types Y, run the calculate() function
    if calc_again == 'Y':
        calculate()

    # If user types N, say good-bye to the user and end the program
    elif calc_again == 'N':
        print('See you later.')

    # If user types another key, run the function again
    else:
        again()

评论是为了帮助程序员，无论是原始程序员还是其他使用或协作项目的人。如果注释不能与代码库一起正确维护和更新，最好不要包含注释，而不是编写与代码相矛盾或将与代码相矛盾的注释。

注释代码时，您应该回答代码后面的 why，而不是 what 或 how。除非代码特别棘手，否则查看代码通常可以知道代码在做什么或它是如何做的。

阻止评论

块注释可用于解释更复杂的代码或您不希望读者熟悉的代码。这些较长形式的注释适用于后面的部分或全部代码，并且也与代码在同一级别缩进。

在块注释中，每一行都以井号和一个空格开头。如果您需要使用多个段落，则应使用包含单个井号标记的行分隔它们。

下面是一个块注释示例，它定义了以下定义的 main() 函数中发生的情况：

# The main function will parse arguments via the parser variable.  These
# arguments will be defined by the user on the console.  This will pass
# the word argument the user wants to parse along with the filename the
# user wants to use, and also provide help text if the user does not
# correctly pass the arguments.

def main():
  parser = argparse.ArgumentParser()
  parser.add_argument(
      "word",
      help="the word to be searched for in the text file."
  )
  parser.add_argument(
      "filename",
      help="the path to the text file to be searched through"
  )
...

块注释通常在操作不太容易理解并因此需要彻底解释时使用。你应该尽量避免过度注释代码，并且应该倾向于相信其他程序员能够理解 Python，除非你是为特定的受众编写的。

内联评论

内联注释出现在语句的同一行，跟在代码本身之后。与其他注释一样，它们以井号和单个空白字符开头。

通常，内联注释看起来像这样：

[code]  # Inline comment about the code

内联注释应该谨慎使用，但可以有效地解释代码的棘手或复杂部分。如果您认为您将来可能不记得您正在编写的代码行，或者您正在与您认识的可能不熟悉代码的所有方面的人合作，它们也很有用。

例如，如果您在 Python 程序中不使用大量 math，您或您的合作者可能不知道以下内容创建了一个复数，因此您可能需要包含关于它的内联注释：

z = 2.5 + 3j  # Create a complex number

内联注释也可以用来解释做某事的原因，或者一些额外的信息，例如：

x = 8  # Initialize x with an arbitrary number

仅在必要时使用在线注释，并且它们可以为阅读程序的人提供有用的指导。

注释掉测试代码

除了使用注释作为记录代码的一种方式之外，井号还可以用于注释掉您在测试或调试当前正在创建的程序时不想执行的代码。也就是说，当您在实现新的代码行后遇到错误时，您可能希望将其中的一些注释掉，看看您是否可以解决确切的问题。

使用井号还可以让您在确定如何设置代码时尝试替代方案。例如，您可能正在决定在 Python 游戏中使用 while 循环还是 for 循环，并且可以在测试并确定哪一个可能最好时注释掉其中一个：

猜测.py

import random

number = random.randint(1, 25)

# number_of_guesses = 0

for i in range(5):
# while number_of_guesses < 5:
    print('Guess a number between 1 and 25:')
    guess = input()
    guess = int(guess)

    # number_of_guesses = number_of_guesses + 1

    if guess < number:
        print('Your guess is too low')

    if guess > number:
        print('Your guess is too high')

    if guess == number:
        break

if guess == number:
    print('You guessed the number!')

else:
    print('You did not guess the number. The number was ' + str(number))

用井号注释掉代码可以让你尝试不同的编程方法，并通过系统地注释和运行程序的一部分来帮助你找到错误的根源。

结论

在您的 Python 程序中使用注释有助于使您的程序对人类（包括您未来的自己）更具可读性。包含相关且有用的适当注释可以使其他人更好地与您在编程项目上协作，并使您的代码的价值更加清晰。

从这里，您可能想阅读 PEP 257 中 Python 的 Docstrings，为您提供更多资源来正确记录您的 Python 项目。