代码风格与可读性

正如本章引言中所强调的，对于机器学习 (machine learning)项目而言，仅仅编写能运行的代码是不够的。代码需要被理解、修改和调试，这通常由多人协作完成，或者在数月后由你自己进行。在这里，代码风格和可读性变得非常重要。一致的风格使代码变得可预测且更易于解析，大大地减少认知负担。

遵循风格指南：PEP 8 的作用

Python 从拥有一个被普遍接受的风格指南——PEP 8 中获益良多。PEP 代表 Python 增强提案，而 PEP 8 是概述 Python 代码风格约定的具体提案。它包括诸如代码布局、命名约定、注释和文档字符串等方面。

强烈建议遵循 PEP 8，因为它提供了一个大多数 Python 开发者都认同的共同基线。当所有人都遵循相同的约定，代码会变得更加统一，使得阅读和整合来自不同来源或团队成员的代码变得更容易。可以将其视为 Python 代码的标准语法和标点符号。

以下是 PEP 8 涵盖的一些基本方面：

• 缩进： 每个缩进级别使用 4 个空格。推荐使用空格而非制表符。在 Python 中，正确的缩进不仅仅是风格问题；它定义了代码块。不一致的缩进会导致 IndentationError。
• 行长度： 代码行长度限制为最多 79 个字符，文档字符串和注释为 72 个字符。这有助于提升可读性，尤其是在并排查看代码或在终端窗口中时。大多数编辑器可以配置显示指导线。
• 空行： 适度使用空行来分隔逻辑部分。顶级函数和类定义周围用两个空行环绕。在类内部，使用一个空行分隔方法定义；在函数内部，使用一个空行表示逻辑中断。
• 导入： 导入语句通常应在单独的行上。

  # 正确：
  import os
  import sys
  
  # 错误：
  import os, sys
  

  按照以下顺序分组导入：
  1. 标准库导入（例如，os、sys）
  2. 相关的第三方库导入（例如，numpy、pandas、sklearn）
  3. 本地应用/库特有的导入 避免使用通配符导入（from module import *），因为它们会使命名空间中存在的名称变得不明确，并可能导致冲突。
• 空格： 在运算符周围和逗号后适当使用空格，以提高可读性。

  # 正确：
  x = 1
  y = 2
  long_variable_name = x + y
  my_list = [1, 2, 3]
  result = calculate_value(x, y)
  
  # 错误：
  x=1
  y =2
  long_variable_name=x+y
  my_list = [1,2,3]
  result = calculate_value( x,y )
  

  避免不必要的空格，例如紧挨着括号内部或逗号之前。
• 命名约定： 命名保持一致非常有帮助。
  • 函数、方法、变量和模块使用 lowercase_with_underscores（小写加下划线）。
  • 常量使用 UPPERCASE_WITH_UNDERSCORES（大写加下划线）。
  • 类名使用 PascalCase（或 CapWords，帕斯卡命名法）。
  • 受保护方法/内部变量名以单个下划线开头（_protected_member）。
  • 强私有（混淆）名称以双下划线开头（__private_member）。谨慎使用。
• 注释和文档字符串：
  • 注释： 使用注释来解释一段代码背后的“原因”，而不是当代码本身已经很清楚时解释“是什么”。确保注释与代码更改保持同步。谨慎使用行内注释。块注释通常适用于其后面的一些（或所有）代码，并且与该代码保持相同的缩进级别。

    # 计算欧几里得距离，为提高比较效率避免使用 sqrt
    dist_sq = (x2 - x1)**2 + (y2 - y1)**2
    if dist_sq < threshold_sq:
         # 处理附近的点
         process_point(p1, p2)
    

  • 文档字符串： 使用用三引号（"""文档字符串在这里。"""）括起来的文档字符串（docstrings）来解释函数、类、模块和方法的作用。第一行应该是简短的摘要。多行文档字符串可以提供关于参数 (parameter)、返回值和行为的更多细节。文档字符串被文档生成器（如 Sphinx）和辅助工具使用。

    def scale_data(data, scaler_type='standard'):
        """使用指定的缩放器对输入数值数据进行缩放。
    
        参数：
            data (pd.DataFrame 或 np.ndarray): 要缩放的输入数据。
            scaler_type (str, optional): 缩放器的类型（'standard' 或 'minmax'）。
                                         默认为 'standard'。
    
        返回：
            np.ndarray: 缩放后的数据。
    
        引发：
            ValueError: 如果提供了未知类型 scaler_type。
        """
        if scaler_type == 'standard':
            # 标准缩放的实现...
            pass
        elif scaler_type == 'minmax':
            # 最小-最大缩放的实现...
            pass
        else:
            raise ValueError(f"未知 scaler_type: {scaler_type}")
        # ... (函数的其余部分)
    

强制执行的工具：代码检查工具和格式化工具

手动检查 PEP 8 合规性可能会很繁琐。幸运的是，存在自动化工具：

• 代码检查工具（例如 Flake8、Pylint）： 这些工具分析您的代码是否存在风格错误（如违反 PEP 8）和潜在的编程错误（如未使用的变量或未定义的名称）。定期运行代码检查工具有助于及早发现问题。
• 格式化工具（例如 Black、YAPF）： 这些工具会自动重新格式化您的代码，使其符合特定的风格标准。例如，Black 以最少的配置强制执行 PEP 8 的严格子集，常被称为“毫不妥协的代码格式化工具”。使用自动格式化工具可以避免风格上的争论，并以最少的精力确保整个代码库的一致性。

将代码检查工具和格式化工具集成到您的开发流程中，例如使用 Git 钩子（稍后讨论）在提交前运行它们，是保持代码质量的非常有效的方法。

编写真正易读的代码

尽管 PEP 8 提供了一个很好的基础，但真正的可读性通常涉及更多主观的考量：

• 有意义的名称： 为变量、函数和类选择描述性的名称。average_training_loss 比 atl 或 avg_loss 清晰得多。尽管 PEP 8 建议使用 lowercase_with_underscores，但名称所传达的含义很重要。如果名称能够明显提高清晰度，请不要害怕它们稍微长一些。
• 简洁与清晰： 力求逻辑直接明了。有时，一个巧妙的单行代码或复杂的列表推导式可能看起来很高效，但比更明确的循环或条件结构更难理解。记住 Python 之禅：“可读性很重要。” 如果您必须添加注释来解释一行复杂代码的作用，请考虑将其重写得更简单。
• 一致性： 尽管 PEP 8 是标准，但单个项目中最重要的规则是内部一致性。如果项目已建立约定（即使与严格的 PEP 8 略有不同），请坚持这些约定。像 Black 这样的工具可以自动帮助强制执行这一点。

花时间编写整洁、易读且风格良好的代码，将在机器学习 (machine learning)项目的整个生命周期中带来回报。它使协作更顺畅，调试更快，维护也更轻松。采用 PEP 8 并使用自动化工具，为达成这一重要品质提供了坚实的基础。