# Code Style

> Use when working with code style — formatting, linting, naming conventions, code organization

- Skill: `liaosw97/code-style` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add liaosw97/code-style`
- Raw SKILL.md: https://api.skillmd.com/api/skills/liaosw97/code-style/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: liaosw97 (https://skillmd.com/u/liaosw97)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/liaosw97/code-style

---


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

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

## 最佳实践
### 1. 命名约定

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

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

### 2. 命名常量

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

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

### 3. 函数设计

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

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

### 4. 错误处理

```typescript
// 实现稳健的错误处理
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. 代码组织

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

## 关键约定
### 命名风格

| 类型 | 风格 | 示例 |
|------|------|------|
| 变量 | camelCase | `userName`, `isActive` |
| 常量 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
| 函数 | camelCase | `getUserById`, `calculateTotal` |
| 类 | PascalCase | `UserService`, `DataParser` |
| 接口 | PascalCase | `IUser`, `IConfig` |
| 文件名 | kebab-case | `user-service.ts` |

### 代码长度

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

### 注释规范

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

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

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