🇨🇳中文介绍

领域聚焦命名

概述

记录实现细节或历史背景的命名会造成混淆。"NewUserAPI" 没有说明它做什么。"ZodValidator" 暴露了内部实现。

核心原则： 命名应说明代码在领域中的功能，而不是它如何构建或替换了什么。

违反这条规则的文字表述，就是违反命名的精神。

何时使用

适用于：

• 变量、函数、类、模块
• 重构现有代码
• 代码审查反馈
• API 设计

特别适用于：

• 重构时（忍不住想加"New"或"Improved"）
• 替换实现时（忍不住想加"Zod"或"MCP"）
• 使用设计模式时（忍不住想加"Factory"或"Manager"）
• 记录变更时（忍不住想加"Unified"或"Enhanced"）

规则

绝不使用实现细节

命名暴露的是"做什么"，而不是"怎么做"。

绝不使用时间上下文

代码存在于当下。不要引用过去或过渡状态。

绝不使用模式名称（除非它们能增加清晰度）

模式是实现细节。大多数模式无助于理解。

// 当模式本身就是目的时，可以使用
class EventEmitter { } // 观察者模式就是它的功能
class CommandQueue { } // 队列模式就是它的功能

命名讲述领域故事

好的命名能构成关于业务逻辑的句子。

// 读起来像领域语言
user.authenticate()
order.calculateTotal()
payment.process()

// 不要这样
user.executeAuthenticationStrategy()
order.runTotalCalculationAlgorithm()
payment.invokeProcessingWorkflow()

快速参考

修改代码时

规则： 绝不在名称中记录旧行为或变更。

危险信号 - 立即停止并重命名

如果你发现自己写了：

• "New"、"Old"、"Legacy"、"Improved"、"Enhanced"
• "Unified"、"Refactored"、"Updated"、"Modern"
• 实现细节（"Zod"、"JSON"、"MCP"、"SQL"）
• 不必要的模式名称（"Factory"、"Builder"、"Manager"）
• 冗余限定词（"Abstract"、"Base"、"Interface"）

立即停止。找一个描述领域中实际用途的名称。

常见辩解

验证

在提交命名前检查：

• 名称描述领域目的
• 没有实现细节
• 没有时间上下文
• 没有不必要的模式名称
• 与其他代码能形成可读的句子
• 没有"new"、"old"、"improved"、"wrapper"

实际示例

不良命名（不要这样做）

class ImprovedZodConfigValidator { }           // ❌ 时间性 + 实现细节
const newAPIClientWithRetry = new Client();    // ❌ 时间性 + 实现细节
function executeEnhancedToolFactory() { }      // ❌ 时间性 + 模式噪音

// 使用它们
const validator = new ImprovedZodConfigValidator();
validator.validateWithNewSchema();

良好命名

class ConfigValidator { }                      // ✅ 领域目的
const apiClient = new Client();               // ✅ 它是什么
function createTool() { }                     // ✅ 它做什么

// 使用它们 - 读起来像领域语言
const validator = new ConfigValidator();
validator.validate();

与其他技能的集成

关于战术性变量命名： 请参阅 skills/naming-variables 了解全面的变量命名技巧（最佳长度、作用域规则、布尔值/集合/限定词的约定、命名作为诊断工具）

关于注释指南： 请参阅 skills/writing-evergreen-comments 了解如何保持注释常青（注释中也不要使用时间上下文）

每周安装次数

–

来源

smithery.ai/ski…d-naming

首次出现

–

</Good>

### Names Tell Domain Stories

Good names form sentences about business logic.

<Good>
```typescript
// Reads like domain language
user.authenticate()
order.calculateTotal()
payment.process()

// Not
user.executeAuthenticationStrategy()
order.runTotalCalculationAlgorithm()
payment.invokeProcessingWorkflow()