代码规范与最佳实践

写出专业、可维护的代码

为什么需要代码规范

代码规范的好处
├── 可读性：代码易于理解
├── 可维护性：方便修改和扩展
├── 协作效率：团队统一风格
└── 减少Bug：良好习惯防患于未然

命名规范

Python命名

# 变量名：小写下划线
user_name = "张三"
max_retry_count = 3

# 常量：全大写下划线
MAX_CONNECTIONS = 100
DEFAULT_TIMEOUT = 30

# 函数名：小写下划线，动词开头
def get_user_info(user_id):
    pass

def calculate_total_price(items):
    pass

def is_valid_email(email):  # 返回布尔值用is/has/can开头
    pass

# 类名：大驼峰
class UserAccount:
    pass

class HttpRequestHandler:
    pass

# 私有属性/方法：单下划线开头
class User:
    def __init__(self):
        self._password = None  # 私有属性

    def _validate(self):  # 私有方法
        pass

JavaScript命名

// 变量：小驼峰
const userName = "张三";
let maxRetryCount = 3;

// 常量：全大写下划线
const MAX_CONNECTIONS = 100;
const API_BASE_URL = "https://api.example.com";

// 函数：小驼峰，动词开头
function getUserInfo(userId) {}
function calculateTotalPrice(items) {}
function isValidEmail(email) {}

// 类：大驼峰
class UserAccount {}
class HttpRequestHandler {}

// React组件：大驼峰
function UserProfile() {}
const TodoList = () => {};

代码格式化

Python格式化

# 使用Black格式化工具
# pip install black
# black myfile.py

# 缩进：4个空格
def example():
    if condition:
        do_something()

# 行长度：不超过88字符（Black默认）
result = some_function(
    argument_one,
    argument_two,
    argument_three
)

# 空行规范
import os
import sys

from mymodule import helper  # 标准库与第三方库之间空一行


class MyClass:
    """类之前空两行"""

    def method_one(self):
        pass
                              # 方法之间空一行
    def method_two(self):
        pass


def top_level_function():    # 顶层函数之前空两行
    pass

使用Linter

# Python: flake8 + black
pip install flake8 black
flake8 myfile.py
black myfile.py

# JavaScript: ESLint + Prettier
npm install -D eslint prettier
npx eslint --init
npx eslint src/
npx prettier --write src/

注释规范

# 单行注释：解释为什么，而不是做什么
# 错误示例
x = x + 1  # x加1

# 正确示例
x = x + 1  # 补偿边界偏移

# 函数文档字符串
def calculate_discount(price: float, discount_rate: float) -> float:
    """
    计算折扣后的价格

    Args:
        price: 原始价格
        discount_rate: 折扣率（0-1之间）

    Returns:
        折扣后的价格

    Raises:
        ValueError: 当折扣率不在0-1之间时

    Example:
        >>> calculate_discount(100, 0.2)
        80.0
    """
    if not 0 <= discount_rate <= 1:
        raise ValueError("折扣率必须在0-1之间")
    return price * (1 - discount_rate)

# TODO和FIXME注释
# TODO: 添加缓存机制提升性能
# FIXME: 边界条件未处理
# HACK: 临时解决方案，需要重构

函数设计原则

# 1. 单一职责：一个函数只做一件事
# 错误示例
def process_user(user_data):
    validate(user_data)
    save_to_db(user_data)
    send_email(user_data)
    log_action(user_data)

# 正确示例
def process_user(user_data):
    validated_data = validate_user(user_data)
    user = save_user(validated_data)
    notify_user_created(user)
    return user

# 2. 参数数量：不超过3-4个
# 错误示例
def create_user(name, email, age, address, phone, role, department):
    pass

# 正确示例
def create_user(user_data: UserCreateRequest):
    pass

# 3. 避免副作用
# 错误示例（修改了输入参数）
def add_tax(prices):
    for i in range(len(prices)):
        prices[i] *= 1.1
    return prices

# 正确示例（返回新列表）
def add_tax(prices):
    return [price * 1.1 for price in prices]

# 4. 早返回，减少嵌套
# 错误示例
def get_user_discount(user):
    if user:
        if user.is_vip:
            if user.years > 5:
                return 0.3
            else:
                return 0.2
        else:
            return 0.1
    else:
        return 0

# 正确示例
def get_user_discount(user):
    if not user:
        return 0
    if not user.is_vip:
        return 0.1
    if user.years > 5:
        return 0.3
    return 0.2

错误处理

# 1. 具体的异常类型
# 错误示例
try:
    do_something()
except:  # 捕获所有异常
    pass

# 正确示例
try:
    do_something()
except ValueError as e:
    logger.error(f"值错误: {e}")
    raise
except IOError as e:
    logger.error(f"IO错误: {e}")
    return None

# 2. 自定义异常
class UserNotFoundError(Exception):
    """用户未找到异常"""
    pass

class InvalidInputError(Exception):
    """无效输入异常"""
    pass

def get_user(user_id: int):
    user = db.find_user(user_id)
    if not user:
        raise UserNotFoundError(f"用户 {user_id} 不存在")
    return user

# 3. 使用上下文管理器
with open("file.txt", "r") as f:
    content = f.read()
# 文件自动关闭，即使发生异常

代码审查清单

## 代码审查检查项

### 功能性
- [ ] 代码是否实现了需求？
- [ ] 边界条件是否处理？
- [ ] 错误情况是否处理？

### 可读性
- [ ] 命名是否清晰有意义？
- [ ] 逻辑是否容易理解？
- [ ] 复杂逻辑是否有注释？

### 可维护性
- [ ] 是否有重复代码？
- [ ] 函数是否过长？
- [ ] 是否遵循项目规范？

### 安全性
- [ ] 是否有SQL注入风险？
- [ ] 是否有XSS风险？
- [ ] 敏感信息是否暴露？

### 性能
- [ ] 是否有不必要的循环？
- [ ] 是否有N+1查询问题？
- [ ] 是否需要缓存？

本章小结

• 命名规范：清晰、一致、有意义
• 格式化：使用工具自动化
• 函数设计：单一职责、避免副作用
• 错误处理：具体异常、优雅降级

→ 继续阅读：44-调试与问题排查