Python 代码编写规范

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

1. 编码风格

1.1 缩进

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

1.2 行宽

# 长行的示例：
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 变量、函数与方法

def calculate_total():
    total_value = 0
    return total_value

2.2 类名

class EmployeeManager:
    pass

2.3 常量

MAX_SIZE = 100

2.4 私有属性与方法

class MyClass:
    def _private_method(self):
        pass

2.5 包名

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

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

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

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 导入顺序

import os
import sys

import requests

from mymodule import MyClass

4.2 避免循环导入

5. 异常处理

5.1 捕获特定异常

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

5.2 使用 finally

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

6. 测试

6.1 编写单元测试

6.2 保持测试的独立性

6.3 测试命名

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

作者：茫茫人海一粒沙