2.5_编码规范入门

2.5 编码规范入门

2.5 代码风格与注释

2.5.1 缩进规范

2.5.1.1 使用空格或制表符（Tab）

Python代码中可以使用空格或制表符（Tab）来缩进，但官方推荐使用空格。

2.5.1.2 Python 官方的推荐：使用 4 个空格

Python官方PEP 8风格指南推荐使用4个空格来进行缩进。

2.5.1.3 嵌套结构中的缩进要求

在嵌套结构中，每个嵌套层级应增加4个空格的缩进。

代码演示：

if True:
    # 第一层嵌套
    print("True")
    if True:
        # 第二层嵌套
        print("Nested True")

输出：

True
Nested True

2.5.1.4 避免混合空格与制表符

混合使用空格和制表符会导致代码风格不一致，也可能引发错误。

2.5.1.5 缩进错误的常见问题及调试方法

常见的缩进错误包括不一致的缩进和混合使用空格与制表符。调试时，可以使用IDE的格式化工具或手动检查缩进。

2.5.2 注释编写

2.5.2.1 单行注释的格式（#）

单行注释使用#符号，放在代码行的开头或行尾。

代码演示：

# 这是一个单行注释
x = 5  # 这也是一个单行注释

输出：

# 无输出，注释不执行

2.5.2.2 多行注释（连续的 # 或者 使用三引号）

多行注释可以使用连续的#或三引号。

代码演示：

"""
这是一个多行注释
可以跨越多行
"""
y = 10

输出：

# 无输出，注释不执行

2.5.2.3 文档字符串（docstring）的使用

文档字符串（docstring）用于描述函数、模块和类的目的和行为。

代码演示：

def my_function():
    """
    这是一个函数文档字符串
    """
    pass

输出：

# 无输出，注释不执行

2.5.2.4 注释的作用：提高代码可读性和可维护性

注释有助于解释代码的目的和逻辑，提高代码的可读性和可维护性。

2.5.2.5 注释规范：简洁、清晰、准确

注释应简洁、清晰、准确，避免冗余和模糊。

代码演示：

# 计算两个数的和
def add(x, y):
    return x + y

输出：

# 无输出，注释不执行

2.5.2.6 避免过度注释，注释应解释“为什么”而非“做什么”

注释应解释代码背后的逻辑和决策，而不是显而易见的操作。

代码演示：

# 错误的注释：将x加到y上
def add(x, y):
    return x + y

# 正确的注释：当x和y为正数时，返回它们的和
def add(x, y):
    return x + y

输出：

# 无输出，注释不执行

2.5.2.7 对复杂代码块的注释规范

对于复杂的代码块，应在代码块之前提供概述和解释。

代码演示：

# 处理复杂的计算逻辑
def complex_calculation(data):
    # 步骤1：数据预处理
    processed_data = preprocess_data(data)
    # 步骤2：应用算法
    result = apply_algorithm(processed_data)
    # 步骤3：返回结果
    return result

输出：

# 无输出，注释不执行

2.5.2.8 注释中的 TODO 和 FIXME 标记

TODO和FIXME标记用于标记需要进一步处理的代码部分。

代码演示：

# TODO: 优化这个算法
def slow_algorithm(data):
    # FIXME: 这里可能会抛出异常
    return data / 0

输出：

# 无输出，注释不执行