Code Style

核心原则

• 可读性至上：代码是写给人看的，其次才是机器
• 一致性优先：在整个项目中保持统一的代码风格
• 简洁明了：避免过度复杂的实现
• 自文档化：代码应该能够自我解释

技术栈

• 代码格式化：Prettier, Black, gofmt
• 代码检查：ESLint, Pylint, Flake8
• 类型检查：TypeScript, mypy, pyright
• 编辑器配置：EditorConfig, .vscode/settings.json

最佳实践

1. 命名约定

// 使用描述性变量名
// 不佳
const d = new Date();
const x = users.filter(u => u.a);

// 推荐
const currentDate = new Date();
const activeUsers = users.filter(user => user.isActive);

2. 命名常量

// 不佳
if (status === 1) { ... }

// 推荐
const STATUS_ACTIVE = 1;
if (status === STATUS_ACTIVE) { ... }

3. 函数设计

// 单一职责原则
// 不佳
function processUser(user) {
  // 验证用户
  // 保存用户
  // 发送邮件
}

// 推荐
function validateUser(user) { ... }
function saveUser(user) { ... }
function sendEmail(user) { ... }

4. 错误处理

// 实现稳健的错误处理
async function fetchData(id: string) {
  try {
    const response = await api.get(`/data/${id}`);
    return { success: true, data: response.data };
  } catch (error) {
    logger.error('Failed to fetch data', { id, error });
    return { success: false, error: error.message };
  }
}

5. 代码组织

// 按功能组织代码
// 推荐的文件结构
src/
├── components/
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.test.tsx
│   │   └── index.ts
│   └── Input/
├── hooks/
├── utils/
└── types/

关键约定

命名风格

代码长度

• 函数长度：不超过 50 行
• 文件长度：不超过 500 行
• 行长度：不超过 100-120 字符
• 参数数量：不超过 4 个

注释规范

/**
 * 计算用户订单总金额
 * @param orders - 订单列表
 * @param discount - 折扣比例（可选）
 * @returns 订单总金额
 */
function calculateTotal(orders: Order[], discount?: number): number {
  // 实现细节...
}

测试

• 使用 Jest、Vitest、pytest 等测试框架
• 测试覆盖率目标：80% 以上
• 编写有意义的测试用例
• 测试边界情况和异常处理

文档

• 使用 JSDoc、docstring 等标准格式
• 为公共 API 编写文档
• 保持文档与代码同步更新