mcpField
C
common-naming-conventions

common-naming-conventions

github.com/xip-online-applications开发047 次安装14 周前更新
代码仓库

关于 common-naming-conventions

为代码、API、数据库及配置等提供一致且易理解的命名指导。适用于编写、修改或审查代码，并涵盖命名、大小写、文件结构和接口等规则。

主要功能

  1. 01使用清晰且一致的英文名称
  2. 02按名称类型采用合适的大小写
  3. 03函数名以动词开头
  4. 04布尔名称采用肯定式前缀
  5. 05文件与目录使用 kebab-case
  6. 06规范集合、接口和 API 命名

适用场景

  1. 01编写或修改代码中的标识符
  2. 02创建数据库架构或 API 端点
  3. 03统一测试、配置及环境变量命名
  4. 04审查代码库中的命名一致性

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/xip-online-applications/skills --skill common-naming-conventions

安装后在 Claude Code 中输入/common-naming-conventions确认已加载。

详细介绍

common-naming-conventions

为所有代码产物采用一致且能体现意图的命名规范，让代码库易于阅读、搜索和自我说明。

适用场景

在以下情况下使用此技能：

  • 编写或修改任何代码（变量、函数、类、接口、文件、目录）
  • 创建数据库架构、API 端点或配置键
  • 为测试文件、测试用例或测试固件命名
  • 定义环境变量、常量或功能标志
  • 审查代码时发现命名不一致或含义不清

说明

1. 使用英语

所有代码、变量名、注释、文档、提交消息和分支名称都必须使用英语编写，不得例外。

2. 使用描述性名称——清晰优先于简短

不必担心名称太长。描述清晰的长名称胜过简短而晦涩的名称。描述清晰的长名称胜过冗长的描述性注释。

  1. 名称必须说明：它存放什么、执行什么操作，或代表什么。
    • 不佳：d、tmp、data、result、info、val、item
    • 良好：elapsedDays、parsedResponse、activeUsers、validationResult
  2. 避免使用无意义的限定词，例如 data、temp、obj、value、stuff。如果你觉得需要附加这些词，说明名称还不够具体。
3. 保持一致

一个概念只使用一个名称。不要使用含义不止一种的名称。命名应与整个团队保持一致，包括非技术团队（市场、管理、产品）。如果项目包含词典或通用语言，请遵循其中的约定。

  • 选择 get、fetch 或 retrieve 中的一个，同一操作不要三者混用。
  • 选择 create、add 或 insert 中的一个，不要交替使用。
  • 对同一实体，不要在 user、account 和 person 之间交替使用。
4. 始终使用肯定表达

绝不要使用带否定含义的布尔名称。否定表达会增加认知负担，迫使读者处理双重否定。

  • 不佳：notEditable、disabled、isNotValid、noResults
  • 良好：isEditable、isEnabled、isValid、hasResults
5. 不要使用缩写

除非缩写比完整单词更常用，否则不要缩写。明确允许使用以下缩写：

  • app 表示 application
  • args 表示 arguments
  • auto 表示 automatic
  • id 表示 identifier
  • info 表示 information
  • init 表示 initialize
  • min 表示 minimum
  • max 表示 maximum
  • param / params 表示 parameter(s)
  • prop / props 表示 property/properties
  • ref 表示 reference
  • ui 表示 user interface
  • util / utils 表示 utility/utilities
  • 常见首字母缩略词：url、http、api、html、css、sql、json

其他内容都必须拼写完整。不要使用 cntUsr、mngr、svc、btn、msg 这类晦涩的缩略形式。

6. 在函数名称中使用动词

函数和方法的名称必须以描述所执行操作的动词开头：do、render、get、format、calculate、send、validate、create、update、delete、find、check、parse、build。

// Bad: does not start with a verb
const valid(value: string): boolean => {}

// Good: starts with a verb
const checkValidity(value: string): boolean => {}
7. 类、变量和属性使用名词

所有非函数名称（类、变量、常量、属性）都必须是名词或名词短语。它们表示事物，而非操作。

// Bad: class name is a verb phrase
class CheckValidity {}

// Good: class name is a noun
class FormValidator {}
8. 布尔值使用前缀词

布尔变量、属性和参数必须以 is、has、will、should、can 或 was 开头，以表示其开关状态。

// Bad: does not include correct prefix
const value = true;
const visible = true;

// Good: includes prefix
const hasValue = true;
const isVisible = true;
9. 大小写约定

根据上下文使用正确的大小写风格。如果项目已有约定，请遵循该约定。否则，使用以下默认规则：

上下文风格示例
局部变量camelCaseuserName, totalAmount
函数 / 方法名称camelCasecalculateTotal(), getUserById()
类 / 接口 / 类型名称PascalCaseUserService, PaymentGateway
常量UPPER_SNAKE_CASEMAX_RETRY_COUNT, DEFAULT_TIMEOUT_MS
枚举成员UPPER_SNAKE_CASE 或 PascalCase（与项目保持一致）ORDER_STATUS_PENDING
环境变量UPPER_SNAKE_CASEDATABASE_URL, API_SECRET_KEY
CSS 类kebab-case（或 BEM）nav-item, btn--primary
数据库表snake_case，使用复数order_items, user_accounts
数据库列snake_casecreated_at, first_name
URL 路径 / API 端点kebab-case，资源使用复数名词/api/user-accounts
10. 文件和文件夹

  1. 使用 kebab-case。 所有文件和文件夹名称都使用小写的 kebab-case。由于有些系统区分大小写，有些则不区分，因此文件名中切勿使用大写字母。

  2. 当文件夹中包含表示同一概念的多个文件时，使用单数文件夹名称（例如，包含辅助文件的组件）：text-input/。

  3. 当文件夹中包含多个相同类型的文件时，使用复数文件夹名称：text-inputs/、validators/。

  4. 当文件只包含一种概念时，在名称中加入文件类型，并用点号分隔：

    // Bad: uses camelCase, no type
customInput.ts

// Good: uses kebab-case and includes type
custom-input.class.ts
custom-input.component.ts
custom-input.service.ts
custom-input.spec.ts
11. 集合和计数

  1. 集合使用复数名词：users、orderItems、activeConnections。

    • 不要在名称中编码类型：避免使用 userList、orderItemArray。

  2. 计数和度量值应包含单位或概念：retryCount、timeoutMs、maxWidthPx。

    • 避免使用 count、timeout、max 这类过于笼统的名称。
12. 接口和实现

  1. 不要在接口名称前加 I，除非项目已有一致的做法。接口名称应体现其能力：Logger、PaymentGateway、UserRepository。

  2. 实现类可以包含适配器或策略名称：ConsoleLogger、StripePaymentGateway、PostgresUserRepository。

13. API 和数据库命名

  1. REST 端点的集合使用复数名词：

    • GET /api/orders — 列表
    • GET /api/orders/{orderId} — 单条记录
    • POST /api/orders — 创建
    • URL 中绝不使用动词：避免使用 /api/getOrders、/api/createOrder

  2. 外键使用相关表的单数形式，并以 _id 为后缀：user_id、order_id。

  3. 时间戳使用过去分词：created_at、updated_at、deleted_at。

  4. 布尔列使用 is_/has_ 前缀：is_active、has_verified_email。

14. 命名决策流程

命名时，请遵循以下流程：

  1. 它是什么？ 判断它属于实体、操作、属性、集合还是标志。
  2. 此上下文要求使用哪种大小写风格？ 根据第 9 节中的表格选择。
  3. 它是否与此代码库中表示同一概念的现有名称保持一致？ 如果已有模式，请遵循该模式。
  4. 它是否采用肯定形式？ 如果它是布尔值，请确保使用肯定前缀。
  5. 新团队成员能否在没有额外上下文的情况下理解这个名称？ 如果不能，请选择更清晰的名称。
  6. 名称是否写全？ 检查其中是否使用了不允许的缩写。

应避免的反模式

  • 单字母变量（无关紧要的循环除外；数组迭代中的 i、j 可以接受，但不能用 u 表示用户）。
  • 匈牙利命名法——在名称中编码类型：strName、arrItems、bIsActive。让类型系统说明类型。
  • 无意义的前缀，例如 my、the、a：myService、theUser、aResult。
  • 复数形式不一致——名为 user 的变量存放用户数组，或名为 orders 的变量存放单个订单。
  • 复制粘贴式命名——handleClick1、handleClick2。如果名称需要数字后缀，说明抽象设计有误。
  • 文件名中使用大写字母——文件和文件夹始终使用小写 kebab-case。

参考资料

评论

支持 Markdown