代码开发专业性：从 “能运行” 到 “可信赖” 的工程实践

# 单字母、模糊命名，无人能懂
a = 10
list1 = []
data = {"name": "Alice"}
tp = 150.75
x = 0.08

# 变量：snake_case（Python）；常量：UPPER_SNAKE_CASE
user_count = 10
active_users = []
user_profile = {"name": "Alice"}
total_price = 150.75
sales_tax_rate = 0.08
MAX_RETRY_TIMES = 3

def process(data):  # 不知道处理什么
    pass

class do_stuff:  # 类名用动词，违背规范
    pass

def calculate_monthly_sales(transactions: list) -> float:
    """计算月度总销售额"""
    return sum(t["amount"] for t in transactions)

class SalesAnalyzer:  # 类名：大驼峰（Python/Java通用）
    """销售数据分析工具类"""
    def __init__(self):
        self.total_sales = 0.0

# ❌ 验证、计算、入库混在一起，无法复用、无法测试
def process_order(order):
    if not order["items"]:
        raise ValueError("订单无商品")
    # 计算总价
    total = sum(item["price"] * item["quantity"] for item in order["items"])
    # VIP折扣
    if order["is_vip"]:
        total *= 0.9
    # 保存数据库
    db.save({"order_id": order["id"], "total": total})
    return total

# ✅ 每个函数只做一件事，可复用、可测试
def validate_order(order: dict) -> None:
    """验证订单合法性"""
    if not order.get("items"):
        raise ValueError("订单商品不能为空")

def calculate_order_total(order: dict) -> float:
    """计算订单最终金额（含VIP折扣）"""
    total = sum(item["price"] * item["quantity"] for item in order["items"])
    return total * 0.9 if order["is_vip"] else total

def save_order_to_db(order_id: str, total: float) -> None:
    """订单入库"""
    db.save({"order_id": order_id, "total": total})

# 上层编排，逻辑一目了然
def process_order(order: dict) -> float:
    validate_order(order)
    total = calculate_order_total(order)
    save_order_to_db(order["id"], total)
    return total

def create_user(name, age, email, phone, address, city, zip_code):
    pass

from dataclasses import dataclass

@dataclass
class UserInfo:
    name: str
    email: str
    age: int | None = None
    phone: str | None = None

def create_user(user_info: UserInfo) -> None:
    """创建用户，参数清晰、易扩展"""
    pass

# ❌ 捕获所有异常，无法定位问题，返回None易引发空指针
def load_config(file_path):
    try:
        with open(file_path) as f:
            return json.load(f)
    except:  # 裸catch，危险！
        print("加载配置失败")
        return None

# ✅ 明确异常类型，自定义异常，声明抛出异常
import json
from typing import Dict

class ConfigLoadError(Exception):
    """配置加载异常基类"""
    pass

def load_config(file_path: str) -> Dict:
    """加载JSON配置文件
    Args:
        file_path: 配置文件路径
    Returns:
        配置字典
    Raises:
        FileNotFoundError: 文件不存在
        json.JSONDecodeError: JSON格式错误
        ConfigLoadError: 其他加载异常
    """
    try:
        with open(file_path, "r", encoding="utf-8") as f:
            return json.load(f)
    except (FileNotFoundError, json.JSONDecodeError) as e:
        raise ConfigLoadError(f"配置加载失败：{str(e)}") from e

# ❌ 废话注释，代码已经说明一切
counter += 1  # 计数器加1
for user in users:  # 遍历用户
    print(user.name)

# ✅ 解释业务决策、算法选择、边界逻辑
# 采用乐观锁：version自增，避免并发覆盖（需求：REQ-2026-038）
@Version
private Long version;

def min_sub_array_len(target: int, nums: list[int]) -> int:
    """双指针法找最短子数组
    时间复杂度：O(n)，空间：O(1)
    弃用前缀和：适配数据流实时输入场景
    """
    left = 0
    total = 0
    min_len = float("inf")
    for right in range(len(nums)):
        total += nums[right]
        while total >= target:
            min_len = min(min_len, right - left + 1)
            total -= nums[left]
            left += 1
    return min_len if min_len != float("inf") else 0

[tool.ruff]
line-length = 88
select = ["E", "F", "I", "N", "W"]  # 开启所有规范检查
ignore = ["E501"]  # 忽略行长检查（Black已处理）

[tool.ruff.pydocstyle]
convention = "google"  # 强制Google文档风格

import pytest
def test_calculate_order_total():
    # Given：准备数据
    order = {"items": [{"price": 100, "quantity": 2}], "is_vip": True}
    # When：执行逻辑
    total = calculate_order_total(order)
    # Then：断言结果
    assert total == pytest.approx(180.0, abs=0.001)