4 掌握注释、语句分隔与 PEP 8 规范

Python 中的注释 (Comments)

注释是代码中不会被解释器执行的部分，它们存在的意义是为了让程序员（包括你自己）更好地理解代码逻辑。

单行注释

Python 中最常用的注释方式是使用井号 #。井号后面的所有内容都会被解释器忽略。

• 独占一行：通常用于解释下方代码块的功能。
• 行末注释：用于解释当前行代码的作用（注意 # 与代码之间应至少保留两个空格）。

代码示例：

# 这是一个单行注释，用于说明下面的变量
user_age = 25  # 这是一个行末注释，解释变量含义

多行注释

当注释内容较多，一行写不下时，可以使用多行注释。

• 连续使用 #：这是官方推荐的方式。
• 使用三引号：虽然 ''' 或 """ 本质上是多行字符串（String Literal），但如果它们没有赋值给任何变量，Python 会忽略它们，因此常被用作多行注释。

代码示例：

# 方法一：官方推荐
# 这是一个多行注释
# 我们通过连续使用井号
# 来实现跨行说明

'''
方法二：使用三个单引号
这里的内容也不会被执行
通常用于临时屏蔽大段代码
'''

"""
方法三：使用三个双引号
这通常用于编写文档字符串（Docstring）
放在函数或类的开头说明其功能
"""
def greet(name):
    """
    这是一个函数的文档字符串。
    功能：打印问候语。
    """
    print(f"Hello, {name}")

语句分隔符 (Statement Separators)

在 C++ 或 Java 等语言中，分号 ; 是必须的语句结束符。但在 Python 中，换行符（Newline） 才是标准的语句分隔符。

为什么要分割？

计算机需要知道一条指令在哪里结束，下一条指令从哪里开始。Python 的设计哲学强调“可读性”，因此它默认使用物理换行（按下 Enter 键）来作为逻辑行的结束，这使得代码看起来更像自然语言。

特殊情况：使用分号 ;

虽然 Python 不强制使用分号，但在一种特殊情况下可以使用：当你希望在一行内写多条语句时。

注意：虽然语法允许，但在 Python 社区中，除了极简单的赋值或调试场景，极不推荐在一行写多条语句，因为这破坏了代码的可读性。

代码示例：

# 标准写法（推荐）：利用换行符分割
x = 10
y = 20
print(x + y)

# 使用分号写法（不推荐，除非在命令行简短脚本中）：
a = 1; b = 2; print(a + b)

跨行书写

有时一条语句太长，需要分成多行，可以使用反斜杠 \ 告诉 Python “这句话还没说完”。注：如果代码在括号 ()、[]、{} 内，则自动支持跨行，无需反斜杠（推荐方式）。

# 使用反斜杠
total = 100 + \
        200 + \
        300

# 使用括号（推荐）
names = [
    "Alice",
    "Bob",
    "Charlie"
]

Python 书写规范：PEP 8

PEP 8 (Python Enhancement Proposal 8) 是 Python 官方提供的代码风格指南。它不是语法强制规则，但它是 Python 开发者共同遵守的“普通话”。遵守 PEP 8 可以让你的代码在任何 Python 程序员眼里都显得专业且亲切。

• 官方文档链接：PEP 8 -- Style Guide for Python Code

具体的常用规范

以下是 PEP 8 中最核心的几条规则：

1. 缩进 (Indentation)：

   • 必须使用 4个空格 进行缩进，不要使用 Tab 键（除非编辑器已配置将 Tab 转为空格）。
   • Python 3 禁止混合使用 Tab 和空格。

2. 行长度 (Line Length)：

   • 每行代码建议不超过 79 个字符。
   • 注释或文档字符串不超过 72 个字符。

3. 空行 (Blank Lines)：

   • 顶层函数和类定义之间空 2 行。
   • 类内部的方法定义之间空 1 行。

4. 导入 (Imports)：

   • import 语句应放在文件开头。
   • 顺序：标准库 -> 第三方库 -> 本地库。
   • 不要一行导入多个库（如 import os, sys 是不好的，应分两行）。

5. 空格 (Whitespace)：

   • 逗号、冒号后要加空格，前面不加。
   • 二元运算符（=, +, - 等）左右各保留一个空格。
   • 但函数参数赋值时等号左右不要空格（如 def func(key=value):）。

6. 命名规范 (Naming Conventions)：

   • 变量名、函数名：使用小写字母加下划线，例如 my_variable, calculate_sum (Snake Case)。
   • 类名：使用首字母大写的驼峰命名，例如 MyClass, UserProfile (Camel Case)。
   • 常量：全部大写，例如 MAX_OVERFLOW。

PEP 8 规范代码示例：

import os
import sys  # 标准库

import requests  # 第三方库 (假设已安装)

# 常量大写
MAX_RETRIES = 5

class DataProcessor:
    """演示类命名的驼峰法则"""

    def __init__(self, data_source):
        self.data = data_source

    def process_data(self, strict_mode=False):
        # 变量和函数名使用小写+下划线
        # 运算符左右留空格
        result_value = 10 + 20
        return result_value

在 VS Code 编辑器中实现 PEP 8 规范

Visual Studio Code (VS Code) 是目前最流行的 Python 编辑器，我们可以通过插件和设置自动让代码符合 PEP 8。

1. 步骤 1：安装 Python 扩展

   确保你已经安装了 Microsoft 官方出品的 Python 插件。

2. 步骤 2：安装格式化工具 (Formatter)

   目前最流行且速度极快的格式化工具是 Black 或 Ruff，或者是经典的 Autopep8。目前我自个安装的是 Ruff。

3. 步骤 3：配置自动格式化

   1. 打开 VS Code 设置（快捷键 Ctrl + , 或 Cmd + ,）。
   2. 搜索 Editor: Default Formatter，在下拉菜单中选择 Black Formatter。
   3. 搜索 Format On Save，勾选 Editor: Format On Save。

效果：

配置完成后，当你写出不符合规范的代码（例如缩进不对、运算符没空格），只要按下 Ctrl + S 保存文件，VS Code 就会瞬间自动将你的代码重新排版，使其完美符合 PEP 8 标准。