命名风格培训草稿

| Comments

我记得郑大有次开课的时候,提到命名这个话题。说有次他跟一个前辈说:命名真的太难了。 前辈说:你终于开窍了。哪天咋们心里也有这个意识,也算是开窍了。(昨晚忘记说这个事了,补充)

编码风格与编码规范

风格是带主观色彩的,有个人爱好的区别。
规范是双刃剑,限制个人风格的随意发挥,让整体有个统一的风格。
规范是一些风格的最佳实践的集合,但仍然是不断进步的。

学习规范,应该从产生背景出发,理解规范背后希望解决的问题,才能更好理解规范,减少抵制情绪,或许还能改进规范。

破窗效应与童子军军规

破窗效应: 一个房子如果窗户破了,没有人去修补,隔不久,其它的窗户也会莫名其妙地被人打破; 一面墙,如果出现一些涂鸦没有被清洗掉,很快的,墙上就布满了乱七八糟、不堪入目的东西; 一个很干净的地方,人们不好意思丢垃圾,但是一旦地上有垃圾出现之后,人就会毫不犹疑地抛,丝毫不觉羞愧。 (选择汽车为例子也可以)
童子军军规: 当你离开一个地方的时候,要让它比你来的时候更整洁干净。

遵守童子军军规,警惕破窗效应。避免对代码大范围进行修改
对于老代码,总会出现新老风格冲突的情况,优化代码应该控制修改的范围和脚步,采用结对或评审的方式规避风险。
加强代码评审, 一个人出错的几率是5%,两个人在同个地方犯错的几率才0.25%。

文件名规则

遵循约定大于配置原则,像java文件名本身是和类名有关系的,对于页面文件和配置文件,同样在命名上要存在相关性。思考下面的问题:
如果你知道其中一个文件,如何找到相关的文件

包名规则

包名规则本身就是有一套指导方针的:
以公司网址进行打头,如com.gmcc
通常会附带项目名,如com.gmcc.boss
项目大的话,还会继续模块化,如com.gmcc.boss.product
模块下面在继续分功能,从分层的角度,可以有com.gmcc.boss.product.action、service、dao、bean之类的包

对于通常的web应用,模块化划分也可以从菜单入手进行分解,至少可以作为参考。模块如果很大,可以再拆分子模块

常用命名法

Camel命名 – java标准命名法
匈牙利命名 – MFC那套,变量名都带类型,如今有IDE智能提示,显得过时了。而且有货不对板的风险。
pascal命名 – 和Camel就第一个单词首字母的区别
下划线命名 – 在c代码、javascript、ruby等脚本中比较常见

类名的选择

主要从业务逻辑,框架要求,模式设计方面考虑:
业务逻辑中按分层命名规范即可 – Action Controller Service Call Dao Business Bean等都是常用的后缀
框架基础类,参考接口命名 – Filter Servlet Comparable *Utils *s
使用设计模式时参考常见命名 – Adapter Chain Visitor Factory Builder

虽然整个代码结构使用分层方式,但还是有地方可以考虑设计模式的,切勿错失良机。
设计模式方面的内容参考四人帮的书籍,关于jdk的设计模式参考酷壳的文章

对于业务系统,最好准备一份业务术语词典,用来指导相关业务功能的命名

方法命名

评价标准:一句话功能描述
通常选择动词加名词的组合,常用的动词并不多。 命名方式可能有所不同,取决于代码的关注点。(默念,参考评价标准)如:
getSubsByCertId – 通过证件号获取用户信息,有强调证件号的意思
getSubs – 获取用户信息,关注结果,可能支持多种方式

变量命名

对于临时变量,通常使用i,j,k,c,b等就可以了。不应该作为其他作用存在。
对于标记标识,选择done,found,success,ok,fail等,切勿使用flag, 评价标准(填空后读起来很顺畅):假如(找到了)…
对于状态,整理一些常用的常量以备使用,如:READY,SUCCESS,FAILED
对于常量,望文生义+注释(注释在这里显得很有必要),修改checkstyle的魔鬼数字时,是学习命名的好机会
对于普通变量,我们常常会带上类型如subsattrList,我觉得subsattrs这种单复数形式会更好。不过这是个习惯问题,不是什么大问题。 变量命名经验要多学习优秀开源代码,会有很多好处。有些变量名是由IDE通过方法名自动生成的,方法名恰当的时候,生成的变量名也是不错的。(总结)

命名技巧都差不多,我经常采用办法:在心里默念需要的功能,转换成方法名/变量名。反复默念几遍命名,看看是否能够像句子一样读出来。

注释

代码不能代替注释,但优先考虑代码的可读性,例如使用方法抽取等手段。
可读性的标准是代码可以像文章一样读出来,保证方法名和注释相符合,忌讳牛头不对马嘴。 坚持这种态度的话,代码质量一定会有所提高。

注释关注类注释和方法注释,方法内注释用于代码难以表达的地方(如某种特殊情况)。
对于外围接口(包括前后台调用),在方法注释中进行详细说明。

需求单号应该适当添加到代码中,我觉得类注释可能是比较合适的地方。
修改bug的代码通常比较烂(现网的是这样),可以标注一下BUG单号等信息。
提交到版本库的日志要清晰,重点关注什么原因修改,修改哪些功能点等,争取让每次提交都有据可依(每次日志都是不一样的)

Comments