一、引言

良好的注释和代码规范让程序更易读和维护，这是程序员的基本素养！

💡 代码是写给电脑看的，也是写给人看的！注释更重要！

二、单行注释

# 这是一个单行注释
# 整行都不会被执行
print("Hello")  # 也可以写在代码后面解释

# 也可以暂时注释掉不想运行的代码
# print("这行不会被执行")

注释的用途

# 1. 解释代码的用途
age = 18  # 用户年龄

# 2. 临时禁用代码（调试用）
# age = 20

# 3. TODO：标记待办事项
# TODO: 后面要加错误处理

三、多行注释（三引号）

"""
这是多行注释
可以写很多行
一般用于说明整个文件
或者是函数的说明
"""

'''
也可以用单引号
效果一样
'''

print("代码开始运行...")

文档字符串（Docstring）

def say_hello():
    """
    打招呼函数
    
    这个函数用于向用户问好
    """
    print("Hello!")

# 查看文档
help(say_hello)

四、PEP8 代码规范（重要！）

PEP8 是 Python 的官方代码风格指南，让代码更统一、更易读！

4.1 缩进（最重要！）

# ✅ 正确：4个空格
if True:
    print("正确缩进")

# ❌ 错误：用 Tab（不推荐）
if True:
	print("不推荐")

# ❌ 错误：混着用
if True:
     print("不对哦")

4.2 每行长度

# ✅ 每行不超过 80 字符（最多 120）
# 太长的话可以换行
text = "这是一行很长很长的文字，" \
       "需要换行来写"

# 或者用括号
text = ("这是一行很长很长的文字，"
        "需要换行来写")

4.3 空行使用

# ✅ 函数之间空两行
def func1():
    pass


def func2():
    pass


# ✅ 函数内可以空一行来分组逻辑
def func():
    print("第一部分")
    
    print("第二部分")

4.4 空格使用

# ✅ 运算符前后加空格
a = b + c
x = (a + b) * (c + d)

# ✅ 逗号后面加空格
func(a, b, c)

# ❌ 不要乱加空格
a = b +c  # 加号后面没空格
func(a,b,c)  # 逗号后面没空格

4.5 命名规范

# ✅ 变量、函数：snake_case
user_name = "张三"
def calculate_area():
    pass

# ✅ 类：PascalCase
class Student:
    pass

# ✅ 常量：UPPER_CASE
PI = 3.14159

# ❌ 避免单字母变量（循环除外）
s = "Hello"  # 不知道 s 是什么
name = "Hello"  # 一看就懂

五、好注释 vs 坏注释

5.1 坏注释（不要写！）

# ❌ 重复代码的注释
a = a + 1  # 把 a 加 1

# ❌ 废话注释
print("Hello")  # 打印 Hello

5.2 好注释（应该写！）

# ✅ 解释原因
# 这里用 dict 查找速度比 list 快
result = {1: 'a', 2: 'b'}

# ✅ 复杂逻辑解释
# 公式：面积 = 长 × 宽，单位：平方米
area = width * height

# ✅ FIXME：标记需要修复的问题
# FIXME: 负数处理有bug
if x > 0:
    pass

六、代码格式工具

6.1 使用 Black 自动格式化

# 安装 Black
pip install black

# 格式化文件
black your_file.py

# 它会自动把不规范的代码改成规范的

6.2 使用 flake8 检查代码

# 安装 flake8
pip install flake8

# 检查代码
flake8 your_file.py

七、完整的规范代码示例

"""
这是一个演示良好代码规范的模块
"""

# 标准库导入
import math

# 第三方库导入
# import requests

# 常量定义
PI = 3.14159
MAX_COUNT = 100


def calculate_circle_area(radius):
    """
    计算圆的面积
    
    参数:
        radius: 圆的半径
        
    返回:
        圆的面积
    """
    if radius < 0:
        raise ValueError("半径不能为负数")
    return PI * radius ** 2


def main():
    """主函数"""
    print("=== 计算圆面积 ===")
    
    try:
        r = float(input("请输入半径："))
        area = calculate_circle_area(r)
        print(f"面积：{area:.2f}")
    except ValueError as e:
        print(f"错误：{e}")


if __name__ == "__main__":
    main()

八、VS Code 相关设置

# 在 VS Code 中设置：
# 1. 安装 Python 插件
# 2. 设置自动格式化
# 3. 启用 PEP8 提示

九、课后练习题

# 练习 1：给下面的代码加注释
# 说明每行做什么

# 练习 2：找出不规范的地方并修正
#   a =5+3
#   def func():
#     print('hi')

# 练习 3：给自己之前写的代码按规范格式化

总结

通过本章学习，你应该已经掌握了「Python 注释与代码规范」的相关知识。

写代码不仅要能运行，还要写得好看、容易看懂！下一章学习常见错误！