Python 代码编写规范

本规范旨在为 Python 项目的代码编写提供一致性指南。它遵循 Python 社区的 PEP 8 标准，并结合了通用的编程最佳实践。

1. 编码风格

1.1 缩进

• 使用 4 个空格 作为缩进，不要使用制表符（Tab）。

def example():
    if True:
        print("Use 4 spaces for indentation.")

1.2 行宽

• 每行代码不应超过 79 个字符，对于文档字符串或注释，行宽不超过 72 个字符。如果代码行太长，可以使用显式换行符 \ 或利用小括号、方括号等自然换行。

# 长行的示例：
def function_with_long_arguments(arg1, arg2, arg3, arg4, arg5):
    pass

1.3 空行

• 在顶级定义（如函数、类）之间留出两个空行。

• 在方法定义和类定义内部的函数之间留出一个空行。

class MyClass:

    def method_one(self):
        pass

    def method_two(self):
        pass

1.4 空格的使用

• 函数调用时，不要在括号内添加空格：

print("Hello")  # 正确
print( "Hello" )  # 错误

• 避免在以下情况中使用多余的空格：
• 列表、字典等容器的括号内不使用空格：

my_list = [1, 2, 3]  # 正确
my_list = [ 1, 2, 3 ]  # 错误

2. 命名规范（naming conventions）

2.1 变量、函数与方法

• 使用 snake_case 命名，即小写字母加下划线分隔单词。

def calculate_total():
    total_value = 0
    return total_value

2.2 类名

• 使用 CamelCase 命名法，即每个单词首字母大写。

class EmployeeManager:
    pass

2.3 常量

• 常量使用全大写字母，单词之间用下划线（underscores）分隔。

MAX_SIZE = 100

2.4 私有属性与方法

• 私有属性或方法使用前导单下划线 _ 来表示，不强制限制，但表示不应从外部访问。

class MyClass:
    def _private_method(self):
        pass

2.5 包名

全小写字母：包名通常应使用小写字母，不使用大写字母。可以使用下划线（_）来分隔单词，但更推荐直接使用小写字母连接。

• 示例: mypackage 或 my_package

公司或项目前缀（可选）：对于公司内部项目，包名可以包含公司或项目的前缀，保证包的唯一性，避免内部冲突。

• 示例: company_projectname

2.6. 特殊方法（魔术方法）

• 特殊方法（也叫魔术方法）是 Python 类中内置(built-in)的、以双下划线开头和结尾的方法。这些方法有特定的行为和用途，比如 __init__、__str__、__repr__ 等。
• 不要为普通方法使用双下划线，这种命名方式应只用于 Python 内部功能。

class MyClass:
    def __init__(self, value):
        self.value = value

    def __str__(self):
        return str(self.value)

3. 注释与文档

3.1 行内注释

• 行内注释应与代码对齐，并与代码留有至少两个空格的间距。

x = x + 1  # 增加计数

3.2 块注释

• 使用块注释为代码片段提供详细的说明，每行应以 # 开头，并与代码对齐。

• # 计算总值
  # 如果项目为空，返回0
  def calculate_total():
      pass
  

3.3 文档字符串（Docstring）

• 为每个模块、类和函数编写文档字符串，说明其功能、参数、返回值等。使用三引号 """ 进行定义。

  def add(a, b):
      """
      Adds two numbers together.
  
      :param a: The first number.
      :param b: The second number.
      :return: The sum of a and b.
      """
      return a + b
  

4. 代码结构

4.1 导入顺序

• 导入应按以下顺序排列，且每类导入之间用一个空行分隔：

  1. 标准库导入
  2. 第三方库导入
  3. 本地模块导入

  import os
  import sys
  
  import requests
  
  from mymodule import MyClass
  

4.2 避免循环导入

• 避免模块之间的循环导入。如果遇到循环导入问题，可以将导入语句移到函数或方法内部，确保在需要时才进行导入。

5. 异常处理

5.1 捕获特定异常

• 避免使用裸 except，应尽量捕获特定的异常类型。

  try:
      result = 10 / 0
  except ZeroDivisionError:
      print("Cannot divide by zero.")
  

5.2 使用 finally

• 如果代码块中有需要无论是否抛出异常都要执行的操作，应使用 finally。

  try:
      file = open("file.txt")
  finally:
      file.close()
  

6. 测试

6.1 编写单元测试

• 使用 unittest 或 pytest 编写单元测试。确保每个函数和模块都有相应的测试覆盖。

6.2 保持测试的独立性

• 测试用例应保持相互独立，不依赖其他测试的执行结果。

6.3 测试命名

• 测试函数应以 test_ 开头，便于测试框架自动识别。

  def test_add():
      assert add(2, 3) == 5