AgentSkillsCN

coding-standards

编码规范与最佳实践——适用于所有编程语言与框架的通用编码标准。

SKILL.md
--- frontmatter
name: coding-standards
description: 编码规范和最佳实践。适用于所有语言和框架的通用编码标准。

编码标准技能

提供通用编码规范和最佳实践指导。

代码组织

文件大小

  • •每文件 200-400 行（典型）
  • •最大 800 行
  • •更多小文件优于少数大文件

组织方式

  • •按功能/领域组织
  • •高内聚，低耦合
  • •清晰的模块边界
code
src/
├── features/           # 按功能组织
│   ├── auth/
│   │   ├── components/
│   │   ├── hooks/
│   │   └── services/
│   └── users/
├── shared/             # 共享组件
└── lib/                # 工具库

命名约定

变量和函数

typescript
// camelCase
const userName = "john"
function getUserById(id: string) {}

类和接口

typescript
// PascalCase
class UserService {}
interface UserData {}
type CreateUserInput = {}

常量

typescript
// UPPER_SNAKE_CASE
const MAX_RETRY_COUNT = 3
const API_BASE_URL = "https://api.example.com"

文件名

code
// kebab-case.ts
user-service.ts
create-user-form.tsx

函数设计

单一职责

每个函数只做一件事

大小限制

  • •最大 50 行
  • •如果更长，拆分成子函数

参数数量

  • •最多 3-4 个参数
  • •更多参数使用对象
typescript
// ❌ 太多参数
function createUser(name, email, age, role, team, manager) {}

// ✅ 使用对象
function createUser(options: CreateUserOptions) {}

错误处理

始终使用 try/catch

typescript
async function fetchUser(id: string) {
  try {
    const response = await api.get(`/users/${id}`)
    return { success: true, data: response.data }
  } catch (error) {
    console.error('获取用户失败:', error)
    return { success: false, error: '无法获取用户信息' }
  }
}

用户友好的错误消息

  • •不暴露技术细节
  • •提供有用的建议

不可变性

禁止直接修改

typescript
// ❌ 修改原始对象
user.name = "new name"
users.push(newUser)

// ✅ 创建新对象
const updatedUser = { ...user, name: "new name" }
const updatedUsers = [...users, newUser]

禁止事项

  • •❌ 硬编码值（使用常量或配置）
  • •❌ 魔法数字（给数字命名）
  • •❌ 深度嵌套（>4 层）
  • •❌ 重复代码（提取函数）
  • •❌ any 类型（使用具体类型）
  • •❌ console.log 在生产代码中