04 - 代码规范¶

# ❌ 不规范的代码 - 难以阅读和维护
def calc(a,b,c):
    d=a+b
    if c!=0:
        return d/c
    else:
        return None

# ✅ 规范的代码 - 清晰易懂
def calculate_average(num1: float, num2: float, divisor: float) -> float | None:
    """
    计算两个数的平均值后除以divisor。

    Args:
        num1: 第一个数字
        num2: 第二个数字
        divisor: 除数

    Returns:
        计算结果，如果divisor为0则返回None
    """
    total = num1 + num2

    if divisor == 0:
        return None

    return total / divisor

# ✅ 使用4个空格缩进（不要用Tab）
def my_function():
    if True:
        print("正确缩进")

# ✅ 运算符两侧加空格
x = 1 + 2
y = (a + b) * (c - d)

# ✅ 逗号后加空格
my_list = [1, 2, 3, 4]
my_dict = {'key': 'value', 'key2': 'value2'}

# ✅ 函数参数默认值两侧不加空格
def greet(name, greeting='Hello'):
    pass

# ❌ 错误示例
def bad_function( ):
    x=1+2  # 运算符两侧没有空格
    my_list=[1,2,3]  # 逗号后没有空格

# 变量名 - 小写，下划线分隔
user_name = '张三'
max_value = 100
is_valid = True

# 常量 - 全大写，下划线分隔
MAX_SIZE = 100
PI = 3.14159
DEFAULT_TIMEOUT = 30

# 函数名 - 小写，下划线分隔
def calculate_total():
    pass

def get_user_info():
    pass

# 类名 - 驼峰命名法
class UserProfile:
    pass

class DataProcessor:
    pass

# 私有变量/函数 - 下划线前缀
_private_var = 10

def _internal_function():
    pass

# 强私有 - 双下划线前缀（会触发名称修饰）
class MyClass:
    def __init__(self):
        self.__very_private = 42

# ✅ 每行不超过79个字符（现在通常放宽到88或100）

# 长参数列表换行
def my_function(
    parameter_one,
    parameter_two,
    parameter_three,
    parameter_four
):
    pass

# 长表达式换行
result = (some_long_variable_name
          + another_long_variable_name
          - yet_another_variable)

# 使用括号隐式换行
my_list = [
    'item_one',
    'item_two',
    'item_three',
    'item_four',
]

# 字符串换行
long_string = (
    "这是一个很长的字符串，"
    "需要分成多行来写。"
)

# 顶级函数和类之间用2个空行
def function_one():
    pass

def function_two():
    pass

class MyClass:
    # 类内部方法之间用1个空行
    def method_one(self):
        pass

    def method_two(self):
        pass

# 函数内部逻辑分组可以用空行
def process_data():
    # 数据加载
    data = load_data()

    # 数据清洗
    cleaned_data = clean_data(data)

    # 数据分析
    results = analyze(cleaned_data)

    return results

# ✅ 导入顺序：标准库 -> 第三方库 -> 本地模块

# 标准库
import os
import sys
from datetime import datetime

# 第三方库
import numpy as np
import pandas as pd
from sklearn.model_selection import train_test_split

# 本地模块
from mypackage import utils
from mypackage.models import MyModel

# ✅ 避免使用通配符导入
# ❌ from module import *

# ✅ 避免循环导入
# 如果必须，使用局部导入

# 行注释 - # 后加1个空格
x = x + 1  # 补偿边界

# 文档字符串（Docstrings）
def calculate_area(length: float, width: float) -> float:
    """
    计算矩形的面积。

    这是一个更详细的描述，可以包含多行。
    解释函数的用途、参数、返回值等。

    Args:
        length: 矩形的长度
        width: 矩形的宽度

    Returns:
        矩形的面积

    Raises:
        ValueError: 如果length或width为负数

    Examples:
        >>> calculate_area(5, 3)
        15.0
    """
    if length < 0 or width < 0:
        raise ValueError("长度和宽度必须为非负数")

    return length * width

class Calculator:
    """
    一个简单的计算器类。

    支持基本的数学运算。

    Attributes:
        history: 存储计算历史
    """

    def __init__(self):
        """初始化计算器。"""
        self.history = []

# ✅ 好的代码示例
class DataProcessor:
    """处理数据的类。"""

    def __init__(self, config: dict) -> None:
        """
        初始化处理器。

        Args:
            config: 配置字典
        """
        self.config = config
        self.logger = logging.getLogger(__name__)

    def process(self, data: pd.DataFrame) -> pd.DataFrame:
        """
        处理数据。

        Args:
            data: 输入数据

        Returns:
            处理后的数据

        Raises:
            ValueError: 如果数据为空
        """
        if data.empty:
            raise ValueError("数据不能为空")

        try:
            result = self._transform(data)
            self.logger.info(f"处理完成: {len(result)} 条记录")
            return result
        except Exception as e:
            self.logger.error(f"处理失败: {e}")
            raise

# 将以下不规范的代码用Black格式化

def badcode(x,y,z):
    a=x+y
    if z>0:
        return a/z
    else:return None

# 找出以下代码中的所有规范问题

import os,sys
import numpy as np

def processData(data):
  x=data+1
  return x

class my_class:
    def __init__(self):
        self.x=1
    def do_something(self):
        print("doing something")