共计 1329 个字符，预计需要花费 4 分钟才能阅读完成。

痛点分析：不规范代码的代价

刚接触 Skill 开发时，很容易写出「能跑就行」的代码。以下是三个典型问题案例：

• 魔法数字泛滥 ：代码中出现大量未解释的3.14、0.618 等字面量，两个月后连自己都看不懂含义
• 200 行巨无霸函数：一个函数处理数据校验、业务逻辑、错误处理全部流程，修改时牵一发而动全身
• 谜语人变量名 ：用tmp、data1 等无意义命名，团队协作时需要反复询问变量用途

规范详解：从混乱到优雅

命名规则：代码的自解释性

• 动词前缀法则 ：函数名用getUserInfo() 明确动作，布尔值用 isValid() 开头
• 匈牙利命名法变体 ：类型前缀简化版（strName 表字符串，nCount表整数）
• 避免单字母变量 ：循环中用index 而非i，除非在数学公式等约定俗成场景

代码结构：SOLID 原则落地

1. 单一职责 ：每个函数只做一件事，如将processOrder() 拆分为validateOrder()+calculatePrice()
2. 开闭原则 ：用策略模式代替if/else 链，新增功能时扩展而非修改原有代码

注释标准：少而精的智慧

def calculate_tax(income: float) -> float:
    """
    计算累进税率（2023 年标准）Args:
        income: 年收入（单位：万元）Returns:
        应缴税额（保留两位小数）"""
    # 税率分段阈值（避免魔法数字）THRESHOLDS = [3.6, 14.4, 30.0]  
    ...

代码对比：规范改造实战

改造前（问题代码）

def f(a, b):
    x = []
    for i in a:
        if i > 5:
            x.append(i * b)
    return x

改造后（规范代码）

def filter_and_scale(numbers: list[float], 
    multiplier: float
) -> list[float]:
    """筛选大于 5 的值并乘以系数"""
    MIN_THRESHOLD = 5.0  # 常量全大写命名
    result = []

    for number in numbers:  # 避免单字母变量
        if number > MIN_THRESHOLD:
            scaled_value = number * multiplier  # 中间变量增加可读性
            result.append(scaled_value)

    return result

改进点注释：
1. 函数名明确表达意图
2. 添加类型标注
3. 魔法数字替换为常量
4. 循环变量语义化
5. 增加 docstring 说明

避坑指南：新手常见雷区

• 过度缩写 ：cust_addr 比ca更易理解，IDE 自动补全不需要过度缩短
• 嵌套地狱：超过 3 层嵌套时，应该拆分子函数或使用早返（early return）
• 重复代码：发现相似代码块时立即考虑提取公用函数

实践建议：从个人到团队

Pre-commit 配置片段

repos:
- repo: https://github.com/psf/black
  rev: 22.10.0
  hooks:
    - id: black
      args: [--line-length=88]

代码审查检查清单

• [] 所有函数是否有类型标注？
• [] 魔法数字是否已常量化？
• [] 单个函数是否能在屏幕一屏内完整显示？

规范不是束缚，而是减少心智负担的工具。刚开始可能需要刻意练习，3 周后会形成肌肉记忆，这时你会发现阅读自己的旧代码竟然变成了一件愉快的事。