分享我对代码命名的一点思考和理解

一个软件最后都会落实到代码,而代码,其背后的架构设计或设计思想或模式固然重要,但我觉得更重要的东西则是良好的命名。混乱或错误的命名不仅让我们对代码难以理解,更糟糕的是,会误导我们的思维,导致对代码的理解完全错误。相反,良好的命名,则可以让我们的代码非常容易读懂,也能向读者正确表达事物以及逻辑的本质,从而使得代码的可维护性就大大增强。

另外一点也许大家还没感受到,那就是良好的命名,以及良好的命名习惯,由于我们总是对每个概念的名称要求非常苛刻,我们会思考这个名称所表达的概念是否正确,该名称是否正确表达了事物的本质或正确反映了某个行为的逻辑。所以,这种对命名的良好思考习惯,可以反过来帮助我们纠正之前的一些错误设计和代码实现;比如,你之前有一个地方可能命名不太准确,然后你发现后面有另一个地方需要用这个名字,且更合理。所以你会发现这个名字对前面的地方就不适合了,从而你会去思考前面的地方可能需要用其他的名字,或者你会发现前面的地方的设计根本就是有问题的。这种就是名字可以促使你思考你的设计是否正确的例子。

我觉得导致混乱或错误的命名的原因主要是:

  1. 没理解事物的本质;
  2. 理解了事物的本质,但不知道命名的重要性或者根本不屑于做好命名;
  3. 理解了事物的本质,也知道命名的重要性,但没能力命名好事物;

所以,要养成良好的命名习惯,我总结了一些我的想法:

  1. 对自己的严格自律,自己写代码时要有一种希望把每个名称都命名好的强烈意识和严格的自律意识;
  2. 要努力分析和思考当前被你命名的事物或逻辑的本质,这点非常关键,思考不深入,就会导致最后对这个事物的命名错误,因为你还没想清楚被你命名的事物是个什么东西;
  3. 在有自律意识和一定的分析能力基础之上,注意命名的方法技巧;要知道何时用动词,何时用名词;以及形容词放哪里,动词放哪里,名词放哪里;也就是小学时的主谓宾要会用;
  4. 要让你的程序的每个相似的地方的命名风格总是一致的。不要一会儿大写,一会儿小写;一会儿全称一会儿简写;一会儿Pascal命名法,一会儿camel命名法或匈牙利命名法;
  5. 不要出现重复的命名;因为通常名称都有嵌套关系,比如类在命名空间里,方法在类里,所有如果一个概念在命名空间里表达了,那就不必再类上再表达一次;
  6. 对于属性或类名,应该总是名词在最后面,名词决定了这个属性代表什么,前面的部分都是用于修饰这个名词;比如,假如现在你有一个服务,然后又是一个关于订单的服务,那就可以命名为OrderService,这样命名就是告诉我们这是一个服务,然后是一个订单服务;再比如CancelOrderCommand,看到这个我们就知道这是一个Command,即命令,然后是什么命令呢?就是一个取消订单的命令,CancelOrder表示取消订单;
  7. 对于方法,应该总是动词开头,名词结尾;比如Order.AddItem(orderItem);这个,表示订单类有一个添加订单项的方法,Add是动词,表示添加,Item是名词表示订单项;

下面我们通过看一些命名的不太好的代码来知道我们命名时哪些细节需要注意:

以上代码中,有很多问题,我们来一一分析:

  1. 方法的参数,第一个字母,一会儿大写的P,一会儿小写的p,不一致;
  2. 第二个参数后面出现多余的空格,不应该;
  3. _paramsTable这个参数为什么要出现下划线,而其他参数没有下划线,不一致;
  4. publishRequest属于camel命名法,而iSignCounter, sStageIsOK这种属于另一种命名法,这种命名c++中用的多,不一致;
  5. foreach循环中,参数名叫instParam,但是后面的集合叫arrParams4SignActions,更对称一点的,应该叫arrInstParam;
  6. 方法的最后两行,出现多余的空格,导致代码格式排版混乱;

从上面的代码我们可以知道,仅仅是通过这些细节,就能发现很多问题。我们写代码时,只要多细心点,多注意点排版是否美观一致、命名是否统一,那代码写出来就会漂亮很多了。下面我们再看看其他的代码:

  1. 上面的代码中,两个参数的命名也不一致,projectid中,i是小写,但是publishId参数,i却是大写,应该都统一为大写;
  2. ViewData中的key,一会儿是全部大写的UPDATE,一会儿是另一种命名,不一致;
  3. 上面的两个红框标出来的if,虽然都是只有一行代码,但是一个有括号,一个没有括号,不一致;且第二个if里出现了多余的空行,格式混乱;

  1. 上面的代码中,函数中,一会儿用IList,是一个接口,一会儿用Dictionary,非接口,不一致;应该都用接口,或者都不用接口;
  2. listOriginal和receiverList命名不一致,要么全部list开头,要么全部List结尾;
  3. foreach循环中,变量的类型叫TDMSOriginalRequirement,但是变量名却叫originalItem,而集合名称又叫listOriginal,应该三者统一;比如foreach (Assembly assembly in assemblies)
  4. +“...”这个地方没有用空格,加号两边应该要空格,这属于格式混乱,不严谨;
  5. createUser这个变量取的很不理想,create是动词,createUser合起来就是创建用户的意思,而他这里要表达的意思是创建人的意思,所以应该叫createdUser或者creator;
  6. 为何originalItemFormat和originalItem的意思可以等价,不合理,如果等价,一开始就要命名为originalItemFormat;而且format是一个东西,动词放在最后,算个啥?

  1. 上面这个类的几个私有字段中,有些带命名空间,有些不带,要么都不带,要么都带;一般命名空间都是在上面声明,后续不需要出现;
  2. ILog logger;这一句有两个问题:1)logger为何没有下划线,不统一;2)为何类名叫ILog,而变量名叫logger,要统一,要么类名叫ILogger,要么变量名叫_log;

上面这两个私有方法,一个是大写开头,一个是小写开头,不一致,混乱;应该要一致;

通过上面的一些例子,我们知道,在我们不经意间,多写了一个空格或者一个空行,或者一个字母的大小写不一致了,都会导致命名的不一致;如果自己没有养成这种平时注重代码命名各种一致性的习惯,那写出来的代码很可能就是像上面那样。我觉得是非常糟糕的。上面我举的例子都只是简单的命名方面的,实际上还有很多其他的东西需要注意,最重要的就是我们必须要严格遵守:

  1. 你的任何一个属性的名字都要和其实际所代表的含义一致;
  2. 你的任何一个方法所做的事情都要和该方面的名字一致;

否则就会给代码带来极大的不可读性。

时间: 2024-08-10 19:11:44

分享我对代码命名的一点思考和理解的相关文章

"简单设计"的一点思考

简单设计是Xp技术实践中开发实践的核心实践,“简单也是价值观中智力色彩最强烈的”,然而,提到简单设计,大家更觉得像原则或者价值观,感觉上还是比较泛,我们不妨从下面的几个角度看一下  1. 为什么要简单设计 <1>. 简单的代码更容易读懂. <2>. 好的设计更能应对变化.  这两点是基于成本和收益考虑的,这里的价值是时间及金钱.更快的满足需求,减少复杂带来的故障排查.修复成本,代码大量修改或者重写成本.  2. 什么是简单设计 对一个团队来讲,简单设计就是团队中每个人都能轻松的读懂

关于后台系统自动生成的一点思考

大量实践发现后台管理程序,其实90%的代码都是相同的,当然是在抛弃复杂逻辑业务的情况下,那么如何能高效的节约这些时间呢,那就是接下来我要说的,对于后台系统自动生成的一些思考. 适用情景: 1.表编号id为自增(基于现在大部分表编号都是自增的情况): 2.没有太复杂业务关联关系,比如表的某一个字段,存储了一个json对象,为了平衡后台用户使用,需要友好的分段展示给用户的定制ui界面:还比如表中存储了外键的多个id,但为了方便用户使用,只能已标签name的方式,给用户展示,等等这些超强业务黏合逻辑的

关于网页脚本代码结构的再思考

在很多说法中,总是建议将我们的javascript脚本加载在网页的最后,并用外部文件的形式,然而事实并不是这样,外挂的文件最好不要太多,脚本结构代码本身才是值得我们思考的问题.我们需要重新思考我们撰写的脚本的执行力,并把更优秀的javascript开发思路融入到我们的开发中. 我在读完了几篇关于javascript和jQuery的性能优化的文章之后,才恍然大悟,我以前所做的很多代码结构优化,最终只是让乌徒帮显得臃肿,于是重新设计脚本代码的结构,无论怎么样,乌徒帮现在的网页打开显得更加流畅了. 1

关于前端的一点思考

关于前端的一点思考 Author:tkorays 最近写前端代码,写着写着就突然开始惆怅.忧伤.愤怒.发狂,我TMD到底在干什么啊! 很多东西写了n遍了,但是还是在不停地写着.自己写过的代码也不想再修改完善.重新利用,只是觉得,可能重新写一遍可能要好点.面对这很多库以及框架,虽然喜爱,但是也是有所顾忌,我只要使用其中的一个功能,根本不需要引入这么大的整个库. 事实上,我们可能在动手写任何代码之前,先要思考下,我们到底要的是什么! 0x00 界面真的需要这么炫酷么 在使用某个界面库之前,我们可能先

让代码更帅一点

博主的私人博客 写代码最重要的是实现功能,但是除了实现功能之外,我们还应该想办法,让代码变得更规范,更漂亮 最近在读<禅与Objective-C编程艺术>和<Effective Objective C 2.0:编写高质量iOS与OS X代码的52个有效方法>,这两本都讲解了代码规范方面的东西,结合自己平时的代码习惯,发现有很多地方自己做的还是不够好,代码写得不够帅,所以总结一下,让以后的代码更帅一点 条件语句 条件语句一定要使用括号,如果不使用括号,if后面的那行代码删除,之后的代

每个程序员需掌握的20个代码命名

代码中到处都需要命名.作为程序员,我们得给类命名,给变量命名,给函数命名,给参数命名,给命名空间命名,等等等等.下面有20条小贴士能帮助你提高你的命名能力. 1.使用能够表达意图的名字 名字得能告诉我们它要做什么,为什么存在,以及是如何工作的.选择能够表达意图的名字,将更有利于我们理解代码. int elapsedTimeInDays; int daysSinceCreation; int daysSinceModification; int fileAgeInDays;</span> 在上面

关于Emit中动态类型TypeBuilder创建类标记的一点思考

  利用TypeBuilder是可以动态创建一个类型,现在有个需求,动态生成一个dll,创建类型EmployeeEx,需要继承原dll里面的Employee类,并包含Employee类上的所有类标记.   网上有很多例子, //创建TypeBuilder. TypeBuilder myTypeBuilder = myModBuilder.DefineType(typeName, TypeAttributes.Public); myTypeBuilder.SetParent(type);   大概

关于模板方法和策略模式的一点思考

该随笔的思想原点,应该算是在两三年前了.当时和一前同事聊天.不知怎得就聊到了Http访问. 一.我记得他和我说过的第一句话,大概是:有没有已经封装好的.比较强大的HttpUtil.也可能是受业务的影响(接口对内).我当时接触到的Http访问,大多比较“规范”,至少有一个接口约束在约定着某些东西,不至于一会传递json,返回json, 一会又要传递xml,返回xml,甚至更奇葩的是,上传个文件.返回0或者1.如果真出现这样的状态,HttpUtil依然能够方便.灵活的适应着各种情况.我想这个Util

关于代码质量的一些思考

关于代码质量的一些思考 今天刚好看到同事写一段代码,跟同事聊到一个代码风格的问题,讨论了一会,也没得出什么结果.回来想了想,之所以大家观点不一样,其实是一开始代码追求的目的就不一样. 1. 可读性 我是一直认为代码的可读性是最重要的目标.太多的书都讲到一个观点:"代码是写给人阅读的,只不过刚好能被计算机执行". 大部分做自己产品的团队,一个项目的维护时间可能是开发时间的5倍以上,而维护的常见内容都是一些小功能以及已有bug的修复.可读性带来的好处就是,非常容易弄清一段功能逻辑,从而定位