1. 项目概述当AI接管代码命名难题为何依旧无解“It’s AI coding era but naming is still hard”——这个标题精准地戳中了当下每一位开发者的心窝子。我们正处在一个前所未有的时代GitHub Copilot、ChatGPT、Claude等AI编码助手已经能流畅地生成函数体、编写单元测试、甚至重构整个模块。它们仿佛一位不知疲倦的初级工程师只要你给出清晰的指令代码就能像流水一样涌出。然而当你看着AI生成的那一长串变量、函数和类时一个古老而棘手的难题再次浮现我该怎么给它们起名字这不仅仅是程序员的一个小烦恼而是软件工程核心矛盾的缩影。AI极大地提升了“制造”代码的效率但它无法替代人类在“设计”层面的核心思考。命名恰恰是设计意图最直接、最浓缩的表达。一个好的名字如calculateMonthlyInterest本身就是一份文档而一个糟糕的名字如processData或tempVar则会让后续的阅读、调试和维护变成一场猜谜游戏。AI可以学习海量的代码模式和语法规则但它难以理解你业务域中那个微妙的概念差异更无法体会一个团队在长期协作中形成的命名默契。这篇文章我想和你深入聊聊这个现象背后的原因。我们会拆解为什么命名如此困难探讨AI在命名辅助上的现状与局限并分享一套我在十多年开发生涯中沉淀下来的、能与AI协作的实用命名策略。这不是要否定AI的价值而是希望我们能成为更聪明的“驾驶员”让AI生成的代码从一开始就具备更高的可读性和可维护性。2. 命名之难深入代码语义的腹地为什么给变量、函数、类起个好名字比写出正确的算法逻辑还要让人头疼这背后是多重复杂因素的叠加。2.1 命名的本质在精确性与简洁性之间走钢丝命名的核心挑战在于它需要在多个相互冲突的目标中寻找最佳平衡点。首先是精确性与简洁性的矛盾。一个名字必须足够精确以准确反映其代表的事物或行为避免歧义。例如一个存储用户邮箱的变量email就比data精确得多。但追求极致精确可能导致名字过长如userPrimaryEmailAddressForNotification这在频繁使用时会让代码变得冗长难读。我们需要在“足够清晰”和“不过度冗长”之间找到那个甜点。其次是具体性与通用性的权衡。名字应该具体到能体现其独特的上下文和职责但又不能过于具体而失去复用性。比如一个处理订单的函数calculateOrderTotal就比doCalculation好但比calculateOrderTotalIncludingTaxAndShippingForUSRegion更具通用性和可读性。最后是业务域与技术域的交融。最好的名字往往能直接映射业务概念。例如在电商系统中使用ShoppingCart、InventoryItem、PaymentGateway这些业务术语远比Container、Object、Processor这类纯技术词汇更能传达意图。这就要求开发者不仅懂技术还要深入理解业务。2.2 认知负荷与上下文丢失当我们写代码时完整的上下文业务逻辑、数据流、设计决策清晰地存在于我们的大脑中。此时我们可能会用一些对自己而言“显而易见”的缩写或简写比如cust代表customerproc代表process。问题在于代码的阅读时间远远超过编写时间。几天、几周甚至几个月后无论是你自己还是其他同事再来阅读这段代码时当初那个完整的“上下文”已经丢失。那个曾经“显而易见”的cust现在需要额外的脑力去解析和回忆。每一个模糊的命名都在给阅读者增加不必要的“认知负荷”积少成多就会让代码库变得难以理解。AI生成代码时同样面临“上下文不足”的问题。你给AI的提示Prompt就是你提供的全部上下文。如果提示是“写一个函数处理用户数据”AI很可能会生成一个名为processUserData的函数。这个命名在技术上是正确的但在业务上是苍白的。它没有说明处理的是什么是验证、清洗、还是转换也没有说明为什么这样处理。2.3 命名的“非功能性”特质我们可以将代码质量的要求分为“功能性”和“非功能性”。功能性需求指代码是否正确执行了计算、完成了操作这通常是可验证、可测试的。AI在这方面表现卓越。而命名连同代码结构、注释、文档一起属于“非功能性”需求更确切地说是“可维护性”需求的核心。它的好坏没有绝对的、机器可判定的标准。getUserInfo和fetchUserProfile哪个更好这取决于项目约定、团队习惯和具体场景。这种高度依赖主观经验和团队共识的特性使得它难以被简化为AI可以完美学习的规则。3. AI在命名辅助上的能与不能理解了命名的难点我们再来客观看待AI在其中的角色。它并非毫无作为但其能力存在清晰的边界。3.1 AI的现有能力模式识别与建议生成当前的AI编码助手在命名方面主要发挥的是“增强型自动补全”和“模式建议”的作用。基于上下文的补全这是最基础也最常用的功能。当你输入const user时AI可能会建议const userName或const userEmail。它通过分析当前文件以及可能的相关文件中的代码模式预测你接下来最可能输入的标识符。这对于减少打字量和保持命名一致性有一定帮助。代码生成时的命名当你要求AI“创建一个函数计算圆的面积”时它通常会生成类似calculateCircleArea(radius)的函数签名。这里AI运用了从海量开源代码中学到的常见命名模式“calculate” “名词” “结果”是一种计算函数的典型命名方式。它能避免一些极其糟糕的命名如func1直接给出一个及格线以上的、符合通用惯例的名字。重命名建议一些高级的AI工具或IDE插件开始提供重命名建议。例如它可能检测到一个名为data的变量在多个地方被用于存储“用户列表”从而建议你将其重命名为userList。这需要AI对代码语义有更深的理解。3.2 AI的核心局限缺乏真正的“理解”与“设计意图”尽管有上述能力AI在命名的核心挑战面前依然显得力不从心。无法理解业务语义这是最根本的局限。AI不知道你所在的公司在“客户”和“用户”概念上的细微区别不知道“订单”在发货前后状态流转的特殊业务规则更不知道团队内部关于“是用fetch还是get作为前缀”的隐性约定。它只能提供泛化的、技术性的命名无法注入业务灵魂。难以把握抽象层次好的命名需要与代码的抽象层次相匹配。一个在模块内部使用的临时变量可能用一个短名字即可而一个公开的API接口则需要一个清晰、完整、自解释的名字。AI很难判断当前正在命名的实体在整个系统架构中处于哪个层次应该暴露多少细节。无法进行创造性抽象当遇到一个全新的、复合的概念时优秀的开发者会创造一个贴切的新名词来封装它。例如将“验证用户权限并记录审计日志”这一系列操作抽象为一个名为AuthorizedAction的类。AI缺乏这种从具体操作中提炼抽象概念并进行创造性命名的能力。它更倾向于组合已知的词汇结果可能冗长或不得要领。对“一致性”的机械理解AI可以学习并模仿单个文件或项目的命名风格如驼峰式、下划线式但它对“语义一致性”的理解是机械的。它可能让所有获取数据的方法都叫getXxx但无法理解在某个上下文中从缓存获取用fetch、从数据库获取用load、从远程API获取用retrieve这种更细腻的语义区分。注意不要过度依赖AI的命名建议。把它看作一个词汇量丰富但缺乏领域知识的助手。它给出的名字是一个不错的起点但你必须用自己的业务知识和设计思维去审查、修正和升华它。4. 与AI协作的实战命名策略既然AI不擅长命名而我们又离不开AI的效率那么正确的姿势就是建立一套人机协作的流程让AI生成代码由我们来主导命名。以下是我在实践中总结的策略。4.1 提示词工程用精准的输入换取更好的输出AI的输出质量极大程度依赖于输入提示Prompt的质量。在命名上我们可以通过优化提示词来引导AI。在提示词中直接指定核心名称这是最有效的方法。不要只说“写一个函数处理订单”而是说请创建一个名为 validateAndCalculateOrderTotal 的Python函数。该函数接收一个订单对象首先验证订单项是否都有库存然后计算所有税费和运费返回订单总金额。这样你直接定义了函数的核心名称AI生成的函数体自然会围绕这个名称展开相关内部变量的命名也会更贴切。在提示词中描述业务概念如果不想直接指定名字也务必在提示词中清晰描述业务场景和概念。差提示词“写个函数处理用户提交的表单。” 好提示词“我们需要一个函数来处理用户在注册流程中提交的‘个人信息表单’。表单包含邮箱、用户名和密码。函数需要验证邮箱格式、检查用户名是否已存在并对密码进行哈希加密。最后将验证通过的数据存入‘待审核用户’临时表。”后一个提示词中“注册流程”、“个人信息表单”、“待审核用户”这些业务术语会引导AI在生成代码时更倾向于使用registrationFlow、personalInfoForm、pendingUser等更具业务语义的词汇。要求AI遵循特定命名约定你可以在对话开始时或提示词中明确要求。请使用驼峰命名法camelCase为变量和函数命名。类名使用帕斯卡命名法PascalCase。布尔变量以‘is’、‘has’、‘can’开头。集合类型变量使用复数形式如 userList。4.2 生成后重构将命名审查作为必要步骤不要接受AI生成代码的“初稿”。将“命名审查与重构”作为集成AI代码后的一个强制性步骤。第一步语义审查。快速浏览AI生成的每个主要标识符类名、函数名、主要变量名。问自己这个名字是否准确反映了它是什么或做什么如果让另一个不熟悉这段代码的同事看他能猜出大概吗将那些模糊的data、result、process、handler重点标出。第二步业务术语对齐。检查这些名字是否与项目词汇表、领域驱动设计DDD中的限界上下文、产品文档中的术语保持一致。确保Customer、Client、User这些概念在代码中得到了清晰、一致的区分。第三步一致性检查。检查命名风格是否与项目现有代码库一致。例如数据访问层是都用Repository后缀还是用DAO服务层是用Service还是ManagerAI可能会混用需要你手动统一。第四步应用命名模式。对于特定类型的代码使用成熟的命名模式可以大幅提升可读性。例如工厂类XxxFactory(如PaymentProcessorFactory)构建器XxxBuilder(如QueryBuilder)策略模式XxxStrategy(如DiscountCalculationStrategy)装饰器XxxDecorator(如LoggingDecorator)事件XxxEvent(如OrderShippedEvent)异常XxxError或XxxException(如ValidationError)在重构时有意识地将AI生成的通用名称套用到这些模式中。4.3 建立与维护项目命名词典对于中大型项目维护一个活的“命名词典”或“术语表”极具价值。这个词典可以是一个简单的团队共享文档、Wiki页面或者代码库中的GLOSSARY.md文件。词典内容应包括核心业务实体及其定义例如“客户Customer”与我们签订购买合同的法律实体。“用户User”实际登录和使用我们系统的个人一个客户下可有多个用户。关键操作的动词约定例如“创建”用create“获取”用fetch指从远程或get指从本地/缓存“计算”用calculate“验证”用validate。项目特定的缩写例如PO代表PurchaseOrder采购订单在代码中可使用PONumber但避免单独使用po。避免使用的模糊词汇黑名单例如禁止使用data,info,util,helper,processor,manager作为类或模块的主名称。当AI生成了代码或者新成员加入时这份词典就是命名的“宪法”。你可以将词典的部分内容作为系统提示词喂给AI长期来看能提升AI生成代码的命名一致性。5. 从原则到实践各代码元素的命名指南让我们把原则落实到具体的代码元素上看看在面对AI生成的代码时我们应该如何调整。5.1 变量与常量命名追求“自解释”变量名是代码中最频繁出现的元素也是最容易写坏的地方。拒绝“万精油”名字AI喜欢生成temp,value,item这类名字。一旦看到立即重构。temp-unverifiedUser,rawInputDatavalue-discountPercentage,totalPriceitem-cartItem,productInInventory使用“名词”或“形容词名词”变量代表一个“事物”。user(好)isActive(布尔值好)activeUser(好)getUser()(这是函数不是变量)集合类型使用复数或明确后缀ListUser users或ListUser userListMapString, Product productMap或Dictionarystring, Product productById常量描述其代表的值而非用途const MAX_RETRY_ATTEMPTS 3;(好)const THREE 3;(差 THREE是什么)5.2 函数与方法命名凸显“动作”与“意图”函数名应该是一个清晰的“命令”或“问题”让人一看就知道它会做什么或返回什么。使用“动词/动词短语宾语”结构calculateTotalPrice(order)sendPasswordResetEmail(toEmailAddress)findCustomerById(id)区分“有副作用”和“无副作用”查询的函数这是一个高级但极其有用的实践。命令有副作用使用“强动词”如saveUser,deleteFile,notifySubscribers。查询无副作用使用“get/find/calculate”等如getUserName,findActiveOrders,calculateTax。 AI通常不会主动区分但你可以通过命名来明确意图例如将AI生成的getUser如果内部有保存操作就改为loadAndUpdateUser。布尔函数应读起来像真值判断isValid(email)hasPermission(user, resource)canUserCheckout(cart)5.3 类与模块命名反映“职责”与“抽象”类和模块的名字是最高层次的抽象应该像一个项目的“目录”让人一眼就知道里面大概有什么。类名使用“名词”或“名词短语”代表一种事物或角色。Order,PaymentGateway,EmailValidator避免OrderManager,PaymentProcessor这种模糊的“管理器”、“处理器”除非它真的是某种设计模式如PipelineProcessor的实现。模块/文件命名反映其内容一个包含User模型类的文件可以叫user.model.ts一个提供用户相关工具函数的文件可以叫user.utils.ts或user.helpers.ts但最好思考这些函数是否应属于某个UserService类避免utils.ts,common.ts,stuff.js这种垃圾抽屉式的命名。接口命名在强类型语言中接口可以加I前缀如IUserRepository但现代更推崇不加前缀通过上下文区分如UserRepository是接口DbUserRepository是实现。团队内部保持一致即可。AI可能随机生成需要你统一。6. 常见命名陷阱与重构实录即使有了策略和指南在实际操作中我们和AI还是会掉进一些典型的命名陷阱。下面是一些真实场景的排查与重构记录。6.1 陷阱一意义缺失的“数据”与“信息”这是AI和初级开发者最常犯的错误。问题代码AI生成def process(data): info extract_info(data) result validate(info) return result诊断data,info,result这三个名字完全没有提供任何信息。我们不知道函数处理什么提取什么信息验证什么返回什么。重构过程查看函数调用上下文和内部实现。假设我们发现这个函数是在处理用户上传的简历文件。重命名参数data-resume_file_path重命名中间变量info-candidate_profile(因为extract_info实际上是从简历中解析出了候选人资料)重命名函数和返回值函数名process过于宽泛。根据其行为验证简历资料重命名为validate_candidate_profile。返回值result重命名为validation_result或is_valid如果是布尔值。重构后代码def validate_candidate_profile(resume_file_path): candidate_profile extract_profile_from_resume(resume_file_path) is_valid check_profile_completeness(candidate_profile) return is_valid现在代码的意图一目了然。6.2 陷阱二动词乏力与语境错位函数名用了动词但动词选择不当或者与业务语境不符。问题代码AI生成// 在一个电商订单履约上下文中 function handle(order) { if (order.status PAID) { make(order); send(order); } } function make(order) { ... } // 实际是创建物流运单 function send(order) { ... } // 实际是通知仓库拣货诊断handle,make,send都是极其普通的动词完全丢失了“订单履约”这个丰富业务语境下的特殊含义。重构过程理解业务动作make对应“创建运单”send对应“下发拣货指令”。选择富有业务含义的动词在履约领域fulfill履行是一个核心动词。重构handle-fulfillOrderIfPaidmake-createShippingLabelsend-notifyWarehouseForPicking重构后代码function fulfillOrderIfPaid(order) { if (order.status PAID) { createShippingLabel(order); notifyWarehouseForPicking(order); } }业务逻辑瞬间清晰。6.3 陷阱三一致性崩坏AI在同一个项目或同一个文件中可能对相似概念使用不同名字。问题代码AI混合生成// 在用户模块中 UserDao userDao new UserDao(); // 这里用 Dao UserRepository userRepo new UserRepositoryImpl(); // 这里用 Repository ListUser userList userDao.getAll(); // 这里又用 Dao User foundUser userRepo.findById(id); // 这里又用 Repo诊断Dao(Data Access Object) 和Repository是类似模式的不同实现或称呼。在同一个项目中混用会造成概念混乱增加理解成本。重构过程查阅项目架构规范确定项目统一采用哪种模式比如 DDD 风格用Repository传统三层架构可能用Dao。全局统一假设确定用Repository。重命名所有相关类、接口和变量将UserDao改为UserRepository将userDao变量改为userRepository。确保整个代码库中对数据访问层的命名保持一致。命名的艺术在于持续的精雕细琢和团队共识的建立。AI时代它把我们从一个名字的“创造者”部分地解放为名字的“编辑者”和“审查者”。我们的核心价值不再是机械地拼写字符而是将深刻的理解、清晰的意图和团队的默契注入到每一个标识符之中。让每一行代码不仅机器能懂几个月后的你和你的队友也能一眼看懂。
AI时代代码命名困境：从模式识别到业务语义的鸿沟
发布时间：2026/5/28 6:12:43
1. 项目概述当AI接管代码命名难题为何依旧无解“It’s AI coding era but naming is still hard”——这个标题精准地戳中了当下每一位开发者的心窝子。我们正处在一个前所未有的时代GitHub Copilot、ChatGPT、Claude等AI编码助手已经能流畅地生成函数体、编写单元测试、甚至重构整个模块。它们仿佛一位不知疲倦的初级工程师只要你给出清晰的指令代码就能像流水一样涌出。然而当你看着AI生成的那一长串变量、函数和类时一个古老而棘手的难题再次浮现我该怎么给它们起名字这不仅仅是程序员的一个小烦恼而是软件工程核心矛盾的缩影。AI极大地提升了“制造”代码的效率但它无法替代人类在“设计”层面的核心思考。命名恰恰是设计意图最直接、最浓缩的表达。一个好的名字如calculateMonthlyInterest本身就是一份文档而一个糟糕的名字如processData或tempVar则会让后续的阅读、调试和维护变成一场猜谜游戏。AI可以学习海量的代码模式和语法规则但它难以理解你业务域中那个微妙的概念差异更无法体会一个团队在长期协作中形成的命名默契。这篇文章我想和你深入聊聊这个现象背后的原因。我们会拆解为什么命名如此困难探讨AI在命名辅助上的现状与局限并分享一套我在十多年开发生涯中沉淀下来的、能与AI协作的实用命名策略。这不是要否定AI的价值而是希望我们能成为更聪明的“驾驶员”让AI生成的代码从一开始就具备更高的可读性和可维护性。2. 命名之难深入代码语义的腹地为什么给变量、函数、类起个好名字比写出正确的算法逻辑还要让人头疼这背后是多重复杂因素的叠加。2.1 命名的本质在精确性与简洁性之间走钢丝命名的核心挑战在于它需要在多个相互冲突的目标中寻找最佳平衡点。首先是精确性与简洁性的矛盾。一个名字必须足够精确以准确反映其代表的事物或行为避免歧义。例如一个存储用户邮箱的变量email就比data精确得多。但追求极致精确可能导致名字过长如userPrimaryEmailAddressForNotification这在频繁使用时会让代码变得冗长难读。我们需要在“足够清晰”和“不过度冗长”之间找到那个甜点。其次是具体性与通用性的权衡。名字应该具体到能体现其独特的上下文和职责但又不能过于具体而失去复用性。比如一个处理订单的函数calculateOrderTotal就比doCalculation好但比calculateOrderTotalIncludingTaxAndShippingForUSRegion更具通用性和可读性。最后是业务域与技术域的交融。最好的名字往往能直接映射业务概念。例如在电商系统中使用ShoppingCart、InventoryItem、PaymentGateway这些业务术语远比Container、Object、Processor这类纯技术词汇更能传达意图。这就要求开发者不仅懂技术还要深入理解业务。2.2 认知负荷与上下文丢失当我们写代码时完整的上下文业务逻辑、数据流、设计决策清晰地存在于我们的大脑中。此时我们可能会用一些对自己而言“显而易见”的缩写或简写比如cust代表customerproc代表process。问题在于代码的阅读时间远远超过编写时间。几天、几周甚至几个月后无论是你自己还是其他同事再来阅读这段代码时当初那个完整的“上下文”已经丢失。那个曾经“显而易见”的cust现在需要额外的脑力去解析和回忆。每一个模糊的命名都在给阅读者增加不必要的“认知负荷”积少成多就会让代码库变得难以理解。AI生成代码时同样面临“上下文不足”的问题。你给AI的提示Prompt就是你提供的全部上下文。如果提示是“写一个函数处理用户数据”AI很可能会生成一个名为processUserData的函数。这个命名在技术上是正确的但在业务上是苍白的。它没有说明处理的是什么是验证、清洗、还是转换也没有说明为什么这样处理。2.3 命名的“非功能性”特质我们可以将代码质量的要求分为“功能性”和“非功能性”。功能性需求指代码是否正确执行了计算、完成了操作这通常是可验证、可测试的。AI在这方面表现卓越。而命名连同代码结构、注释、文档一起属于“非功能性”需求更确切地说是“可维护性”需求的核心。它的好坏没有绝对的、机器可判定的标准。getUserInfo和fetchUserProfile哪个更好这取决于项目约定、团队习惯和具体场景。这种高度依赖主观经验和团队共识的特性使得它难以被简化为AI可以完美学习的规则。3. AI在命名辅助上的能与不能理解了命名的难点我们再来客观看待AI在其中的角色。它并非毫无作为但其能力存在清晰的边界。3.1 AI的现有能力模式识别与建议生成当前的AI编码助手在命名方面主要发挥的是“增强型自动补全”和“模式建议”的作用。基于上下文的补全这是最基础也最常用的功能。当你输入const user时AI可能会建议const userName或const userEmail。它通过分析当前文件以及可能的相关文件中的代码模式预测你接下来最可能输入的标识符。这对于减少打字量和保持命名一致性有一定帮助。代码生成时的命名当你要求AI“创建一个函数计算圆的面积”时它通常会生成类似calculateCircleArea(radius)的函数签名。这里AI运用了从海量开源代码中学到的常见命名模式“calculate” “名词” “结果”是一种计算函数的典型命名方式。它能避免一些极其糟糕的命名如func1直接给出一个及格线以上的、符合通用惯例的名字。重命名建议一些高级的AI工具或IDE插件开始提供重命名建议。例如它可能检测到一个名为data的变量在多个地方被用于存储“用户列表”从而建议你将其重命名为userList。这需要AI对代码语义有更深的理解。3.2 AI的核心局限缺乏真正的“理解”与“设计意图”尽管有上述能力AI在命名的核心挑战面前依然显得力不从心。无法理解业务语义这是最根本的局限。AI不知道你所在的公司在“客户”和“用户”概念上的细微区别不知道“订单”在发货前后状态流转的特殊业务规则更不知道团队内部关于“是用fetch还是get作为前缀”的隐性约定。它只能提供泛化的、技术性的命名无法注入业务灵魂。难以把握抽象层次好的命名需要与代码的抽象层次相匹配。一个在模块内部使用的临时变量可能用一个短名字即可而一个公开的API接口则需要一个清晰、完整、自解释的名字。AI很难判断当前正在命名的实体在整个系统架构中处于哪个层次应该暴露多少细节。无法进行创造性抽象当遇到一个全新的、复合的概念时优秀的开发者会创造一个贴切的新名词来封装它。例如将“验证用户权限并记录审计日志”这一系列操作抽象为一个名为AuthorizedAction的类。AI缺乏这种从具体操作中提炼抽象概念并进行创造性命名的能力。它更倾向于组合已知的词汇结果可能冗长或不得要领。对“一致性”的机械理解AI可以学习并模仿单个文件或项目的命名风格如驼峰式、下划线式但它对“语义一致性”的理解是机械的。它可能让所有获取数据的方法都叫getXxx但无法理解在某个上下文中从缓存获取用fetch、从数据库获取用load、从远程API获取用retrieve这种更细腻的语义区分。注意不要过度依赖AI的命名建议。把它看作一个词汇量丰富但缺乏领域知识的助手。它给出的名字是一个不错的起点但你必须用自己的业务知识和设计思维去审查、修正和升华它。4. 与AI协作的实战命名策略既然AI不擅长命名而我们又离不开AI的效率那么正确的姿势就是建立一套人机协作的流程让AI生成代码由我们来主导命名。以下是我在实践中总结的策略。4.1 提示词工程用精准的输入换取更好的输出AI的输出质量极大程度依赖于输入提示Prompt的质量。在命名上我们可以通过优化提示词来引导AI。在提示词中直接指定核心名称这是最有效的方法。不要只说“写一个函数处理订单”而是说请创建一个名为 validateAndCalculateOrderTotal 的Python函数。该函数接收一个订单对象首先验证订单项是否都有库存然后计算所有税费和运费返回订单总金额。这样你直接定义了函数的核心名称AI生成的函数体自然会围绕这个名称展开相关内部变量的命名也会更贴切。在提示词中描述业务概念如果不想直接指定名字也务必在提示词中清晰描述业务场景和概念。差提示词“写个函数处理用户提交的表单。” 好提示词“我们需要一个函数来处理用户在注册流程中提交的‘个人信息表单’。表单包含邮箱、用户名和密码。函数需要验证邮箱格式、检查用户名是否已存在并对密码进行哈希加密。最后将验证通过的数据存入‘待审核用户’临时表。”后一个提示词中“注册流程”、“个人信息表单”、“待审核用户”这些业务术语会引导AI在生成代码时更倾向于使用registrationFlow、personalInfoForm、pendingUser等更具业务语义的词汇。要求AI遵循特定命名约定你可以在对话开始时或提示词中明确要求。请使用驼峰命名法camelCase为变量和函数命名。类名使用帕斯卡命名法PascalCase。布尔变量以‘is’、‘has’、‘can’开头。集合类型变量使用复数形式如 userList。4.2 生成后重构将命名审查作为必要步骤不要接受AI生成代码的“初稿”。将“命名审查与重构”作为集成AI代码后的一个强制性步骤。第一步语义审查。快速浏览AI生成的每个主要标识符类名、函数名、主要变量名。问自己这个名字是否准确反映了它是什么或做什么如果让另一个不熟悉这段代码的同事看他能猜出大概吗将那些模糊的data、result、process、handler重点标出。第二步业务术语对齐。检查这些名字是否与项目词汇表、领域驱动设计DDD中的限界上下文、产品文档中的术语保持一致。确保Customer、Client、User这些概念在代码中得到了清晰、一致的区分。第三步一致性检查。检查命名风格是否与项目现有代码库一致。例如数据访问层是都用Repository后缀还是用DAO服务层是用Service还是ManagerAI可能会混用需要你手动统一。第四步应用命名模式。对于特定类型的代码使用成熟的命名模式可以大幅提升可读性。例如工厂类XxxFactory(如PaymentProcessorFactory)构建器XxxBuilder(如QueryBuilder)策略模式XxxStrategy(如DiscountCalculationStrategy)装饰器XxxDecorator(如LoggingDecorator)事件XxxEvent(如OrderShippedEvent)异常XxxError或XxxException(如ValidationError)在重构时有意识地将AI生成的通用名称套用到这些模式中。4.3 建立与维护项目命名词典对于中大型项目维护一个活的“命名词典”或“术语表”极具价值。这个词典可以是一个简单的团队共享文档、Wiki页面或者代码库中的GLOSSARY.md文件。词典内容应包括核心业务实体及其定义例如“客户Customer”与我们签订购买合同的法律实体。“用户User”实际登录和使用我们系统的个人一个客户下可有多个用户。关键操作的动词约定例如“创建”用create“获取”用fetch指从远程或get指从本地/缓存“计算”用calculate“验证”用validate。项目特定的缩写例如PO代表PurchaseOrder采购订单在代码中可使用PONumber但避免单独使用po。避免使用的模糊词汇黑名单例如禁止使用data,info,util,helper,processor,manager作为类或模块的主名称。当AI生成了代码或者新成员加入时这份词典就是命名的“宪法”。你可以将词典的部分内容作为系统提示词喂给AI长期来看能提升AI生成代码的命名一致性。5. 从原则到实践各代码元素的命名指南让我们把原则落实到具体的代码元素上看看在面对AI生成的代码时我们应该如何调整。5.1 变量与常量命名追求“自解释”变量名是代码中最频繁出现的元素也是最容易写坏的地方。拒绝“万精油”名字AI喜欢生成temp,value,item这类名字。一旦看到立即重构。temp-unverifiedUser,rawInputDatavalue-discountPercentage,totalPriceitem-cartItem,productInInventory使用“名词”或“形容词名词”变量代表一个“事物”。user(好)isActive(布尔值好)activeUser(好)getUser()(这是函数不是变量)集合类型使用复数或明确后缀ListUser users或ListUser userListMapString, Product productMap或Dictionarystring, Product productById常量描述其代表的值而非用途const MAX_RETRY_ATTEMPTS 3;(好)const THREE 3;(差 THREE是什么)5.2 函数与方法命名凸显“动作”与“意图”函数名应该是一个清晰的“命令”或“问题”让人一看就知道它会做什么或返回什么。使用“动词/动词短语宾语”结构calculateTotalPrice(order)sendPasswordResetEmail(toEmailAddress)findCustomerById(id)区分“有副作用”和“无副作用”查询的函数这是一个高级但极其有用的实践。命令有副作用使用“强动词”如saveUser,deleteFile,notifySubscribers。查询无副作用使用“get/find/calculate”等如getUserName,findActiveOrders,calculateTax。 AI通常不会主动区分但你可以通过命名来明确意图例如将AI生成的getUser如果内部有保存操作就改为loadAndUpdateUser。布尔函数应读起来像真值判断isValid(email)hasPermission(user, resource)canUserCheckout(cart)5.3 类与模块命名反映“职责”与“抽象”类和模块的名字是最高层次的抽象应该像一个项目的“目录”让人一眼就知道里面大概有什么。类名使用“名词”或“名词短语”代表一种事物或角色。Order,PaymentGateway,EmailValidator避免OrderManager,PaymentProcessor这种模糊的“管理器”、“处理器”除非它真的是某种设计模式如PipelineProcessor的实现。模块/文件命名反映其内容一个包含User模型类的文件可以叫user.model.ts一个提供用户相关工具函数的文件可以叫user.utils.ts或user.helpers.ts但最好思考这些函数是否应属于某个UserService类避免utils.ts,common.ts,stuff.js这种垃圾抽屉式的命名。接口命名在强类型语言中接口可以加I前缀如IUserRepository但现代更推崇不加前缀通过上下文区分如UserRepository是接口DbUserRepository是实现。团队内部保持一致即可。AI可能随机生成需要你统一。6. 常见命名陷阱与重构实录即使有了策略和指南在实际操作中我们和AI还是会掉进一些典型的命名陷阱。下面是一些真实场景的排查与重构记录。6.1 陷阱一意义缺失的“数据”与“信息”这是AI和初级开发者最常犯的错误。问题代码AI生成def process(data): info extract_info(data) result validate(info) return result诊断data,info,result这三个名字完全没有提供任何信息。我们不知道函数处理什么提取什么信息验证什么返回什么。重构过程查看函数调用上下文和内部实现。假设我们发现这个函数是在处理用户上传的简历文件。重命名参数data-resume_file_path重命名中间变量info-candidate_profile(因为extract_info实际上是从简历中解析出了候选人资料)重命名函数和返回值函数名process过于宽泛。根据其行为验证简历资料重命名为validate_candidate_profile。返回值result重命名为validation_result或is_valid如果是布尔值。重构后代码def validate_candidate_profile(resume_file_path): candidate_profile extract_profile_from_resume(resume_file_path) is_valid check_profile_completeness(candidate_profile) return is_valid现在代码的意图一目了然。6.2 陷阱二动词乏力与语境错位函数名用了动词但动词选择不当或者与业务语境不符。问题代码AI生成// 在一个电商订单履约上下文中 function handle(order) { if (order.status PAID) { make(order); send(order); } } function make(order) { ... } // 实际是创建物流运单 function send(order) { ... } // 实际是通知仓库拣货诊断handle,make,send都是极其普通的动词完全丢失了“订单履约”这个丰富业务语境下的特殊含义。重构过程理解业务动作make对应“创建运单”send对应“下发拣货指令”。选择富有业务含义的动词在履约领域fulfill履行是一个核心动词。重构handle-fulfillOrderIfPaidmake-createShippingLabelsend-notifyWarehouseForPicking重构后代码function fulfillOrderIfPaid(order) { if (order.status PAID) { createShippingLabel(order); notifyWarehouseForPicking(order); } }业务逻辑瞬间清晰。6.3 陷阱三一致性崩坏AI在同一个项目或同一个文件中可能对相似概念使用不同名字。问题代码AI混合生成// 在用户模块中 UserDao userDao new UserDao(); // 这里用 Dao UserRepository userRepo new UserRepositoryImpl(); // 这里用 Repository ListUser userList userDao.getAll(); // 这里又用 Dao User foundUser userRepo.findById(id); // 这里又用 Repo诊断Dao(Data Access Object) 和Repository是类似模式的不同实现或称呼。在同一个项目中混用会造成概念混乱增加理解成本。重构过程查阅项目架构规范确定项目统一采用哪种模式比如 DDD 风格用Repository传统三层架构可能用Dao。全局统一假设确定用Repository。重命名所有相关类、接口和变量将UserDao改为UserRepository将userDao变量改为userRepository。确保整个代码库中对数据访问层的命名保持一致。命名的艺术在于持续的精雕细琢和团队共识的建立。AI时代它把我们从一个名字的“创造者”部分地解放为名字的“编辑者”和“审查者”。我们的核心价值不再是机械地拼写字符而是将深刻的理解、清晰的意图和团队的默契注入到每一个标识符之中。让每一行代码不仅机器能懂几个月后的你和你的队友也能一眼看懂。
