代码风格指南

简介

良好的代码风格是编写可维护代码的关键。本指南介绍推荐的代码风格约定和最佳实践。

基本原则

1. 清晰性优先

// ✅ 好的命名
const getUserById = (userId) => { ... }

// ❌ 不好的命名
const g = (id) => { ... }

2. 一致性

在项目中保持一致的代码风格：

• 使用相同的命名约定
• 遵循相同的格式化规则
• 保持一致的文件结构

3. 文档化

为复杂的逻辑添加注释：

/**
 * 计算斐波那契数列的第 n 项
 * @param {number} n - 要计算的项数
 * @returns {number} - 斐波那契数列的第 n 项
 */
const fibonacci = (n) => {
  if (n <= 1) return n;
  return fibonacci(n - 1) + fibonacci(n - 2);
};

命名约定

变量和函数

• 使用 camelCase：myVariable, getUserData
• 使用描述性名称：userList 而不是 data

常量

• 使用 UPPER_SNAKE_CASE：MAX_RETRIES, API_BASE_URL

类

• 使用 PascalCase：UserService, DataProcessor

文件

• 使用 kebab-case：user-service.ts, data-processor.js

格式化规则

缩进

• 使用 2 个空格缩进（不使用制表符）

行长度

• 限制每行最多 100 个字符

空格

• 操作符周围添加空格：a + b 而不是 a+b
• 逗号后添加空格：[1, 2, 3]

分号

• 总是使用分号结束语句

注释规范

单行注释

// 计算总价
const total = price * quantity;

多行注释

/*
 * 处理用户输入数据
 * 1. 验证输入格式
 * 2. 清理特殊字符
 * 3. 返回处理后的数据
 */
const processInput = (input) => { ... };

JSDoc

/**
 * 获取用户信息
 * @param {string} userId - 用户 ID
 * @param {Object} options - 配置选项
 * @returns {Promise<Object>} 用户信息对象
 */
async function getUser(userId, options = {}) { ... }

错误处理

使用 try-catch

try {
  const data = await fetchData();
  processData(data);
} catch (error) {
  console.error("数据处理失败:", error);
  // 适当的错误恢复逻辑
}

错误消息

提供清晰、有用的错误消息：

// ✅ 好的错误消息
throw new Error(`无法加载用户 ${userId}: 用户不存在`);

// ❌ 不好的错误消息
throw new Error("错误");

代码组织

文件结构

src/
├── components/
│   ├── Button.tsx
│   └── Input.tsx
├── utils/
│   ├── helpers.ts
│   └── validators.ts
└── services/
    └── api.ts

导出顺序

// 1. React 导入
import React from 'react';

// 2. 第三方库导入
import { Button } from 'antd';

// 3. 本地导入
import { useAuth } from './hooks';

// 4. 类型定义
interface Props { ... }

// 5. 组件/函数定义
export const MyComponent = () => { ... };

性能优化

避免不必要的计算

// ✅ 使用 useMemo
const memoizedValue = useMemo(() => {
  return expensiveCalculation(a, b);
}, [a, b]);

// ❌ 每次渲染都计算
const value = expensiveCalculation(a, b);

懒加载

const LazyComponent = React.lazy(() => import("./LazyComponent"));

安全最佳实践

输入验证

function sanitizeInput(input) {
  // 移除危险字符
  return input.replace(/[<>]/g, "");
}

避免敏感信息

// ❌ 不要硬编码敏感信息
const apiKey = "sk-1234567890";

// ✅ 使用环境变量
const apiKey = process.env.API_KEY;

工具和配置

推荐工具

• ESLint - 代码检查
• Prettier - 代码格式化
• EditorConfig - 编辑器配置

示例配置

// .prettierrc
{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 100,
  "tabWidth": 2
}

总结

遵循这些代码风格指南将帮助你编写：

• 更易读的代码
• 更易维护的代码
• 更少的错误

记住，一致性是关键！选择一套规则并在整个项目中坚持使用。

---

← 返回指南