编码规范

编码规范

来源: everything-claude-code 技能库

概述

coding-standards 是适用于所有项目的通用编码标准，包括 TypeScript、JavaScript、React 和 Node.js 开发的最佳实践和模式。

核心理念

代码首先是写给人看的，其次才是给机器运行的。

核心原则

1. 可读性优先

• 代码读的次数比写多
• 清晰的变量和函数名
• 自文档化代码优于注释
• 一致的格式

2. KISS（保持简单）

• 最简单的可行方案
• 避免过度工程
• 不做过早优化
• 易于理解 > 巧妙代码

3. DRY（不要重复）

• 提取公共逻辑到函数
• 创建可复用组件
• 模块间共享工具函数
• 避免复制粘贴编程

4. YAGNI（你不会需要它）

• 不要在需要之前构建功能
• 避免投机性的抽象
• 只在需要时添加复杂性
• 从简单开始，需要时重构

TypeScript/JavaScript 标准

变量命名

// 好：清晰明确
const userList = [];
const isActive = true;
const maxRetries = 3;
const createdAt = new Date();

// 不好：模糊或缩写
const lst = [];      // list 缩写
const ia = true;     // isActive 缩写
const mr = 3;        // maxRetries 缩写
const cat = new Date();  // createdAt 缩写

函数命名

// 动词前缀
function getUser(id: string): User | undefined {}
function createUser(data: UserData): User {}
function updateUser(id: string, data: Partial<UserData>): User {}
function deleteUser(id: string): void {}

// 布尔值函数
function isValid(email: string): boolean {}
function hasPermission(user: User, action: string): boolean {}
function canAccess(resource: Resource, user: User): boolean {}

常量命名

// 全部大写加下划线
const MAX_RETRY_COUNT = 3;
const API_BASE_URL = 'https://api.example.com';
const HTTP_STATUS_OK = 200;

// 或使用 enum
enum HttpStatus {
    OK = 200,
    NOT_FOUND = 404,
    INTERNAL_ERROR = 500,
}

代码组织

文件结构

src/
├── components/       # React 组件
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.styles.ts
│   │   └── index.ts
├── hooks/           # 自定义 hooks
├── utils/           # 工具函数
├── services/        # API 服务
├── types/          # 类型定义
├── constants/      # 常量
└── index.ts        # 入口文件

导入顺序

// 1. React/框架
import React, { useState, useEffect } from 'react';

// 2. 外部库
import axios from 'axios';
import { useQuery } from 'react-query';

// 3. 类型
import { User, Post } from './types';

// 4. 组件
import Button from './components/Button';

// 5. 工具
import { formatDate, debounce } from './utils';

// 6. 样式/资源
import './styles.css';

函数最佳实践

函数长度

// 好：单一职责
function validateEmail(email: string): boolean {
    const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    return regex.test(email);
}

function formatUserName(firstName: string, lastName: string): string {
    return `${firstName} ${lastName}`.trim();
}

// 不好：一个函数做太多
function processUserAndSaveAndNotifyAndLog(input: any): Promise<void> {
    // 超过 50 行...
}

参数数量

// 好：参数少
function createUser(name: string, email: string): User {
    return { name, email, createdAt: new Date() };
}

// 使用对象选项
function createUser(options: CreateUserOptions): User {
    const { name, email, role = 'user' } = options;
    return { name, email, role, createdAt: new Date() };
}

interface CreateUserOptions {
    name: string;
    email: string;
    role?: 'user' | 'admin';
}

提前返回

// 好：提前返回减少嵌套
function processUser(user: User | null): string {
    if (!user) {
        return 'No user provided';
    }

    if (!user.isActive) {
        return 'User is inactive';
    }

    return `Hello, ${user.name}!`;
}

// 不好：嵌套金字塔
function processUser(user: User | null): string {
    if (user) {
        if (user.isActive) {
            return `Hello, ${user.name}!`;
        } else {
            return 'User is inactive';
        }
    } else {
        return 'No user provided';
    }
}

React 最佳实践

组件结构

// 好：清晰分离
interface ButtonProps {
    onClick: () => void;
    children: React.ReactNode;
    variant?: 'primary' | 'secondary';
}

export function Button({ onClick, children, variant = 'primary' }: ButtonProps) {
    return (
        <button
            className={`btn btn-${variant}`}
            onClick={onClick}
        >
            {children}
        </button>
    );
}

useState 最佳实践

// 好：多个 useState
const [name, setName] = useState('');
const [email, setEmail] = useState('');
const [isLoading, setIsLoading] = useState(false);

// 不好：状态混在一起
const [formData, setFormData] = useState({ name: '', email: '', isLoading: false });

useEffect 清理

// 好：清理副作用
useEffect(() => {
    const subscription = api.subscribe(handleData);

    return () => {
        subscription.unsubscribe(); // 清理！
    };
}, [api]);

// 不好：内存泄漏
useEffect(() => {
    api.subscribe(handleData);
    // 没有清理！
}, []);

错误处理

try-catch

// 好：具体错误处理
async function fetchUser(id: string): Promise<User> {
    try {
        const response = await api.get(`/users/${id}`);
        return response.data;
    } catch (error) {
        if (axios.isAxiosError(error)) {
            if (error.response?.status === 404) {
                throw new Error('User not found');
            }
            throw new Error('Failed to fetch user');
        }
        throw error;
    }
}

Error Boundary

class ErrorBoundary extends React.Component<
    { children: React.ReactNode },
    { hasError: boolean }
> {
    state = { hasError: false };

    static getDerivedStateFromError() {
        return { hasError: true };
    }

    render() {
        if (this.state.hasError) {
            return <div>Something went wrong.</div>;
        }
        return this.props.children;
    }
}

模拟场景

场景 1：代码审查

✅ 正确做法：
1. 检查命名是否清晰
2. 检查函数是否单一职责
3. 检查是否有重复代码
4. 检查错误处理
5. 检查类型安全

❌ 错误做法：
1. 只关注功能正确性
2. 忽略代码风格
3. 忽略性能问题
4. 忽略安全漏洞

场景 2：重构旧代码

✅ 正确做法：
1. 先添加测试
2. 小步重构
3. 每次重构后运行测试
4. 保持原有行为
5. 提交可工作的代码

❌ 错误做法：
1. 大改特改
2. 不添加测试
3. 重构和功能改动一起做

场景 3：命名规范

✅ 正确做法：
1. 使用有意义的名称
2. 动词前缀表示动作
3. 布尔值用 is/has/can 前缀
4. 常量全部大写

❌ 错误做法：
1. 单字母命名
2. 模糊的缩写
3. 中英文混用

核心命令

# 代码检查
eslint .
pylint .

# 格式化
prettier --write .
black .

# 类型检查
tsc --noEmit
mypy .

# 打包
webpack build
vite build

# 测试
jest
vitest

避坑指南

重复代码

错误：复制粘贴代码 正确：提取到函数或组件

函数过长

错误：一个函数做很多事 正确：单一职责原则

硬编码

错误：魔法数字和字符串 正确：提取到常量

忽略类型

错误：使用 any 正确：定义具体类型

速查卡片

何时使用

• 新项目开始
• 代码审查
• 重构旧代码
• 新成员加入

何时不用

• 一次性脚本
• PoC 原型
• 个人学习

关键要点

• 可读性优先
• KISS 原则
• DRY 原则
• YAGNI 原则

常见错误

• 重复代码
• 函数过长
• 硬编码
• 忽略类型

深度解读

代码质量维度

1. 可读性 - 代码是否容易理解
2. 可维护性 - 修改是否容易
3. 可测试性 - 是否容易测试
4. 性能 - 效率是否满足要求
5. 安全性 - 是否有漏洞

团队规范价值

• 统一风格减少认知负担
• 新成员快速上手
• 减少代码审查时间
• 提高协作效率

自动化工具

• ESLint - 代码检查
• Prettier - 代码格式化
• TypeScript - 类型检查
• Husky - Git hooks
• lint-staged - 提交前检查

关联技能

技能	关系
python-patterns	Python 规范
golang-patterns	Go 规范
code-review	代码审查

快速开始

1. 选择工具 - ESLint + Prettier
2. 配置规则 - 创建配置文件
3. 集成 IDE - VS Code 设置
4. CI/CD - 添加检查步骤
5. 持续改进 - 定期回顾规范

---

官方原文: coding-standards SKILL.md

---

💡 提示：代码是写给人看的，代码可读性决定团队效率。