5. 注释与代码规范

为什么需要注释

代码是写给人看的，顺便让机器执行。六个月后的你，看到当初写的代码，很可能一脸懵逼：“这坨东西是我写的？”

注释就是给代码加的「旁白」，解释这段代码在做什么、为什么这么做。好的注释能让协作者（包括未来的自己）少花十倍时间理解代码。

单行注释

用 # 开头，同一行后面的内容都是注释，Python 会忽略。

# 这是一个单行注释
print("Hello")  # 注释也可以跟在代码后面

多行注释

Python 没有专门的多行注释语法，但有两种常用写法：

写法一：多个 #

# 这是多行注释的第一行
# 这是第二行
# 这是第三行
print("Hello")

写法二：三引号字符串

"""
这是文档字符串（docstring）。
通常放在函数或模块开头，用来说明整体功能。
虽然它是个字符串，但如果不赋值给变量，Python 会直接丢弃，
所以也能当作多行注释用。
"""
print("Hello")

注释写什么、不写什么

该写的注释：

• 解释「为什么」这么写，而不是「做了什么」（代码本身已经说明了做了什么）
• 复杂算法的关键步骤
• 容易让人困惑的边界情况
• 临时解决方案（TODO / FIXME）

# TODO: 这里的超时时间是临时值，上线前需要根据压测结果调整
TIMEOUT = 30

不该写的注释：

# 不好的注释示例
x = x + 1  # x 增加 1（废话，代码本身已经说得很清楚）

PEP 8 规范简介

PEP 8 是 Python 官方的代码风格指南。你不需要一次性背下来，但核心规则越早知道越好。

缩进

用 4 个空格缩进，不要用 Tab。

# 正确
def hello():
    print("world")

# 错误（Tab 缩进）
def hello():
	print("world")

行长度

每行不超过 79 个字符。现代屏幕很宽，但这个限制强制你写更简洁的代码，也方便并排查看两个文件。

如果一行太长，用括号换行：

# 正确：括号内换行不需要反斜杠
result = some_function(arg1, arg2,
                       arg3, arg4)

# 也可以用反斜杠换行（不推荐，容易漏写）
long_string = "这是一段很长的文本，" \
              "需要分成两行来写"

空行

• 函数与函数之间：空 2 行
• 类的方法之间：空 1 行
• 导入语句分组：标准库、第三方库、本地模块之间各空 1 行

import os
import sys

import requests

from mymodule import helper


def func_a():
    pass


def func_b():
    pass

空格规则

# 正确：运算符两边加空格
x = 1 + 2

# 错误：运算符两边不加空格
x=1+2

# 正确：函数参数默认值不加空格
def greet(name, greeting="Hello"):
    pass

# 错误：默认值两边加空格
# def greet(name, greeting = "Hello"):

命名约定

Python 社区有一套约定俗成的命名规矩：

类型	命名方式	示例
变量、函数	小写，下划线分隔	user_name, get_value()
常量	全大写，下划线分隔	MAX_SIZE, PI
类名	大驼峰（首字母大写）	UserInfo, HttpRequest
私有属性/方法	单下划线前缀	_internal_value
强私有属性	双下划线前缀	__private_attr
模块名	小写，可带下划线	my_module.py

代码格式化工具

手动调整格式很烦，让工具帮你做。最常用的是 black：

pip install black
black your_script.py    # 格式化单个文件
black .                 # 格式化当前目录下所有文件

VSCode 和 PyCharm 都可以配置保存时自动格式化。开启后，按 Ctrl + S 的瞬间，代码就整整齐齐了。

写代码像写文章，格式工整、注释清晰是基本功。刚开始可能觉得麻烦，但坚持几周就会养成肌肉记忆。记住一句话：代码是写给人看的，只是顺便让机器执行。

---