1. 缩进

1.1 缩进的定义和作用

在 Python 中，缩进用于标识代码块。与许多编程语言不同，Python 没有用 {} 来包裹代码块，而是依靠缩进来确定层次结构。因此，缩进在 Python 中是强制的，它不仅用于代码的可读性，还决定了代码的执行结构。

1.2 缩进的基本规则

1. 缩进一致性：在同一个代码块中，所有缩进必须保持一致。Python 的默认缩进规范是 4 个空格，也可以用一个 Tab 键，但不能混合使用。
2. 代码块结构：Python 通过缩进来识别不同的代码块。例如，在 if、for、while 等语句后面缩进的部分被认为是属于这些语句的代码块。

1.3 缩进示例

以 if 语句为例，来看一下如何使用缩进来定义代码块：

age = 23

if age >= 18:
    print("你已成年")         # 这个缩进属于 if 语句的代码块
    print("可以参与投票")     # 这个也是 if 语句的代码块
else:
    print("你未成年")         # 这个属于 else 语句的代码块

在上面的代码中，if 和 else 语句下面的代码都缩进了 4 个空格，这表示这些缩进的代码是属于各自条件的代码块。

1.4 缩进错误示例

如果缩进不一致或不符合 Python 规范，就会导致 IndentationError 错误。

if age >= 18:
    print("你已成年")
     print("可以参与投票")  # 不一致的缩进，将导致 IndentationError

在这个例子中，第二行和第三行的缩进不一致（一个是 4 个空格，另一个是 5 个空格），Python 会报错。

1.5 嵌套缩进

当代码块有多层嵌套时，每一层嵌套都需要再缩进一次，通常每一层使用 4 个空格。

age = 23
is_student = True

if age >= 18:
    print("你已成年")
    if is_student:
        print("你是成年学生")   # 进一步嵌套的代码块，每层缩进 4 个空格
    else:
        print("你不是学生")
else:
    print("你未成年")

在这个例子中，if 语句中的嵌套 if 和 else 语句都进一步缩进了 4 个空格。

2. 注释

注释是对代码的解释说明，用于帮助开发者理解代码的作用和逻辑。Python 支持单行注释和多行注释。

2.1 单行注释

在 Python 中，单行注释使用 # 符号。# 后的内容不会被 Python 解释器执行，通常用于解释代码行的功能。

• 用法：# 后面可以跟任何注释内容。通常单行注释会放在代码上方或者旁边。

• 示例：

  age = 23  # 定义年龄变量，值为23

• 多行单行注释：如果需要多行注释，但每行只有简单的注释内容，可以在每行前面加 #。

  # 这是一个多行注释
  # 说明这段代码的作用
  # 以及每行的功能

2.2 多行注释

多行注释在 Python 中通常使用三个单引号 ''' 或三个双引号 """ 括起来的内容。这种方式的注释主要用于函数或类的文档字符串（docstring），也可以用于多行注释，但在一般代码中单行注释更为常见。

• 用法：在代码块前或后使用 '''注释内容''' 或 """注释内容""" 包裹多行注释。

• 示例：

  '''
  这是一个多行注释
  可以用来描述整个函数的作用
  或者解释代码逻辑
  '''

2.3 函数和类的文档字符串（docstring）

当编写函数、类或模块时，建议在定义的第一行使用多行注释来描述它的功能。这样可以为函数或类提供文档说明，方便其他人了解它的用途。

• 函数文档字符串示例：

  def greet_user(name):
      """打印问候用户的消息"""
      print(f"你好, {name}")

• 类文档字符串示例：

  class Student:
      """这是一个学生类，用于存储学生的基本信息"""
  
      def __init__(self, name, age):
          """初始化学生的名字和年龄"""
          self.name = name
          self.age = age

2.4 注释的规范与最佳实践

• 注释要简洁明了：注释应该清楚明白地解释代码的意图，而不是重复代码本身。例如，以下注释是多余的：

  count = 0  # 将计数变量设置为0

  可以改为：

  count = 0  # 记录用户的数量

• 注释重要逻辑或复杂代码：对于重要的代码逻辑和复杂的部分，应提供详细的解释。
• 避免过多注释：不要在每一行都添加注释，过多的注释会影响可读性。只在关键地方添加注释即可。

3. 结合缩进和注释的代码示例

结合缩进和注释，以下是一个示例代码，展示了如何使用合理的缩进和注释来编写清晰、易读的 Python 代码：

def check_eligibility(age, city):
    """
    检查用户的资格，根据年龄和所在城市决定是否符合条件
    参数:
    age (int): 用户的年龄
    city (str): 用户所在的城市
    返回:
    bool: 如果符合资格返回 True，否则返回 False
    """
    
    # 判断年龄是否大于等于18
    if age >= 18:
        # 如果年龄合格，继续检查城市
        if city == "上海":
            return True  # 满足条件，返回 True
        else:
            return False  # 城市不符合条件，返回 False
    else:
        return False  # 年龄不符合条件，返回 False


# 调用函数并打印结果
user_age = 23
user_city = "上海"
is_eligible = check_eligibility(user_age, user_city)  # 检查用户是否符合资格
print(is_eligible)  # 打印结果

在这个示例中：

• 缩进：代码中使用 4 个空格来缩进每个代码块，保持一致性。
• 注释：代码中的每个逻辑步骤都配有简洁明了的注释，文档字符串则详细说明了函数的用途和参数。