---
globs: *.ts,*.vue
alwaysApply: false
---

---

description: 编写整洁、可维护且易于人类阅读的代码指南。在编写或审查代码时遵循这些规则，以确保代码的一致性与质量。
globs:

---

# 整洁代码规范

## 常量优于魔法数字

• 用命名常量替代硬编码值  
• 使用描述性强的常量名，明确说明数值的用途  
• 将常量置于文件顶部，或存入专用的常量文件中

## 有意义的命名

• 变量、函数与类名应直接体现其用途  
• 名称需阐明其存在的意义及使用方式  
• 避免使用缩写（除非是通用约定俗成的缩写）

## 智能注释

• 不要为代码的功能写注释——让代码自身具备文档性  
• 用注释解释「为何这样做」而非「做了什么」  
• 为 API、复杂算法及非直观的副作用添加文档说明

## 单一职责

• 每个函数仅负责完成一项具体任务  
• 函数应保持短小精悍，聚焦单一目标  
• 若一个函数需要额外注释解释其功能，则说明它需要拆分

## DRY（不要重复自己）

• 将重复代码提取为可复用的函数  
• 通过合理抽象共享通用逻辑  
• 维护单一数据源（避免多位置维护同一数据）

## 整洁结构

• 将相关代码集中存放  
• 按逻辑层级组织代码  
• 文件与文件夹命名保持统一规范

## 封装

• 隐藏具体实现细节  
• 暴露清晰易懂的接口  
• 将嵌套的条件判断拆分为命名良好的独立函数

## 代码质量维护

• 持续进行代码重构  
• 尽早修复技术债务  
• 确保离开时的代码比接手时更整洁

## 测试

• 修复 bug 前先编写测试用例  
• 保持测试代码的可读性与可维护性  
• 覆盖边界条件与异常场景的测试

## 版本控制

• 编写清晰的提交信息（说明修改内容与目的）  
• 提交小而专注的变更（避免大而全的提交）  
• 使用有业务含义的分支名（如 feature/login、fix/payment-error）