Lidessen's land
← All Skills
npx skills add lidessen/readme --skill concept-namingGitHub ↗
SKILL.mdMarkdown

Concept Naming

让读者凭名称就能形成接近真实职责的预期。先保证语义成立,再在目标读者熟悉的表达中选择; 名称的收益是少一次猜测、翻译或查定义,不是显得专业、新颖或尽量短。 先复用准确的领域术语和已核实的项目用法;需要判断生态惯例或解决语义争议时,比较相关开源项目 的实际用法。不要先凭词义造出名字,再找案例佐证。

从对象而非同义词开始

先读定义、关键操作与调用位置,用不包含候选名字的一句话说明:它是什么、做什么、 由谁使用,以及与邻近对象的区别。分清业务概念、数据、提供能力的对象、一次操作及其结果。 同一主题的几种对象不必共享一个名字:一次执行、执行请求与执行器有不同语法角色。

缺少事实时给出条件建议;若两个候选实际对应不同职责,指出尚未确定的设计选择。 不能通过改名默默增加职责。对象职责不清时先指出歧义,不靠更长的名字补全设计。

多看开源项目,建立可比较的用法

先检查所在模块及调用方的词汇。新领域抽象、实质语义争议或需要判断业内惯例时,主动寻找 多个独立开源项目中承担相近职责的对象。 检索围绕职责、使用场景与架构关系展开,不能只搜索自己已经想到的候选名。 先看同语言、同领域和用户熟悉的生态,再用邻近领域检验其他叫法;不要求为了套名字改变本项目职责。

比较必须越过单个项目和单个候选:查看不同项目如何表达相同职责,也查看同一个词在不同项目中的含义。 不要在第一个看起来合适的结果处停止。若已有资料全来自同一框架家族或互相移植的项目, 继续补充独立来源;同源用法不能算多份独立证据。项目知名度是选样线索,不能代替语义匹配。

阅读实际定义、主要方法和调用示例,并连同相邻类型、模块名一起理解。 记录足以比较的信息:项目与源码链接或本地路径、实际名称、承担的职责、与目标的相似处和关键差异。 按需做短表,不复制整套代码或另建永久术语台账。优先复用本地开源 checkout,缺少代表性用法时再检索上游。 搜索摘要、名字出现次数和 README 中的一次提及都不足以证明该命名适合。

当继续查看相关独立项目主要重复已有用法、关键候选的语义差别已清楚时收束; 若用法仍分歧,就说明它是生态或领域选择,不强行宣布一个全行业标准。 无法查证时明确证据不足,只给暂定判断,不把个人词感写成业内惯例。

已有项目名称是理解成本的一部分,但不是正确性的证明。若与通行语义相反,说明其误导和迁移代价; 若准确且已经形成一致用法,没有实质收益就保留。不要把某个框架的叫法泛化成全行业标准。

领域已有精确术语时保留它,不为“代码味”换成含混的技术词。 已有准确合同和一致词汇的确认任务可复用已核实的依据,包括公共接口;是否需要跨项目比较 取决于尚未解决的语义和惯例判断,不由接口是否公开决定。

比较名称造成的预期

围绕有实际差别的候选比较,不凑同义词清单,也不设机械评分。

  • 准确性:名字是否暗示不存在的存储、顺序、恢复、并发或所有权保证?
  • 惯用性:目标读者看到它会想到什么既有概念,那些预期在这里成立吗?
  • 区分度:它与同一调用链中的请求、任务、执行、结果会不会混淆?
  • 用法:放进真实类型声明、方法调用、目录路径和说明句后是否自然?上下文已给出的信息是否重复?

前后缀也有语义,但不能仅凭 Builder、Provider、Store、Repository、Journal、Executor 的字面区别裁决。 以已核实的合同和实际用法为依据,判断这些词在当前语境下是否自然。更长、更具体、列出更多职责 不自动等于更准确;模块路径和调用关系已经表达的信息不必塞进名称。 缩写、比喻和生造复合词只有在读者能稳定理解时才使用。 语言的命名约定影响大小写、动词与接口外形,但不能替代职责判断。

做一次反向检验:暂时遮住定义,只看候选名和一个调用例子,写出读者可能预期的行为; 与实际合同对照。需要反复补“这里不是通常那个意思”才能成立的名称,应换名或承认抽象尚未定清。 这是语义推演,不宣称等同于真实读者测试。

交付与改名范围

先展示实际采用的依据:项目合同与已有用法,或参考项目的实际用法和适用差异;再给主推荐、 一句职责说明与选择理由。 保留可核对的来源;明确哪些是源码事实,哪些是熟悉度与理解成本的判断。 确有取舍时保留有意义的备选及适用条件,不必给每个对象凑出新名字。 多个对象一起命名时先检查整组关系,再用紧凑对照表呈现。可以明确推荐保留原名。 已有名称没有具体误导、又没有证据充分的更自然表达时,默认保留;新概念则优先从观察到的用法中选择。 不要只翻译词义,也不要用更顺口的名字替代未解决的设计判断。

用户只要求命名建议时不修改代码。要求落地改名时,更新范围内的定义、调用、示例和文档引用, 检查序列化字段、公开 API、数据格式及兼容影响;符号改名不自动授权迁移持久数据或改变协议。 最后说明建议依据、未确定的语义与实际验证范围,不以格式检查通过证明名字容易理解。