如何优雅地为程序中的变量和函数命名

简言之,根据语意来选择词汇,别无它法……然而,有时我们会不知用什么词汇更合适。

当你想到某个抽象的东西,你更倾向于最先想到的词语,除非你故意不这样,这些词也会抢着出现,直到模糊或改变你的想法。

当你想到一个具体的对象,你觉得词穷,然后你想描述的已经看到了,然后你继续寻找更适合它的词。

哈哈,命名竟成了编程中最难的事~

Martin Fowler曾经在一篇文章中曾经引用过Phil Karlton的话:

There are only two hard things in Computer Science: cache invalidation

and naming things.

他说这句话在很长的一段时间内都是他最喜欢的话。可见命名对于广大的程序员来说的确是个大问题。

对于我们中国人来说,问题可能出在两个方面:

– 自打学编程开始就没被教育过要重视命名。

这可以在谭浩强的《C语言入门》一书中可见一斑。《C语言入门》可以说是很多程序员在大学时学习的第一门编程语言使用的教材。而本书通篇都是各种

a,b,c,x,y,z 的命名方式。这种poor naming的方式被广大程序员纷纷效仿,导致如今在很多项目代码中随处可见。

– 命名需要一定的英文功底,而国内程序员的英文水平参差不齐。

很多程序员被教育后开始逐渐重视命名,但是受限于英文水平,不知道使用什么合适的英文词汇来命名。有的甚至直接把中文直译为英文的方式命名,或者直接用拼音来命名,反而得不偿失。

命名的重要性我想不需要过于强调。如今的软件开发早已不是求伯君那种单枪匹马的时代。你写下的每一行代码都会在不久的以后被团队的其他人甚至你自己多次查看。如果是个开源项目,那么更会被全球各地的人查看源代码。所以代码的可读性就变得尤为重要。如果读者能够轻松读出你的代码的意图,那么就说明你的命名功底相当扎实。

比如在一个管理系统中,你使用这样的代码: a = b * c

很容易让人摸不着头脑,虽然程序能够正常运作,但恐怕没人敢轻易修改这行他们不了解的代码。而如果修改成为这样: weeklypay =

hours_worked * pay_rate; 那恐怕极少有人不懂这行代码的意图。

糟糕的命名也会导致大量无谓的注释,这是一个很容易跳进去的陷阱。下一段代码怕别人不明白你的意图,那么就加上注释。这貌似是一个很精妙的想法,实际上却南辕北辙。比如以下的注释:

int d; // elapsed time in days

貌似很容易让人读懂,但是问题还是很多。首先注释不能跟着所有的引用,在定义处了解了d的含义,继续往下看的话却很容易忘记;其次代码更新了,很可能会忘记修改注释,反而给把读者带入歧途。

与其用这样的注释,还不如直接重命名: int elapsedTimeInDays; 这样清晰易懂,还不用维护注释,何乐而不为?

那么如何着手来提高的自己的命名技巧那?

首先寻找一份公认的代码规范,并严格按照这样的标准执行。比如google开源了自己内部使用的语言编码规范,我们可以直接拿来使用。比如请看Google

Java的style guide,相当详实。除此之外还有C++等。这里收集了Google对各种语言的编码规范,非常具有参考价值。

标准的代码规范中的每一条都是有胜出的理由,值得我们遵从。但某些命名问题不一定只有一种最好的解决方式,这就需要团队自己建立起约定。比如对于Java单元测试类的命名方式,不同的团队可能不一样。比如有的团队喜欢以should开头,有的喜欢test开头,有的喜欢骆驼命名法,有些喜欢下划线命名法,每种方式有各自的利弊,没有一种能完全脱颖而出,所以需要团队自行制定。一旦确定使用某一种,那么一定要保持一致。

某些命名规范其实是可以进行自动化检查的,比如在Java应用的构建过程中可以引用checkStyle这款插件,对命名进行一些基本的检查,比如方法名、变量名是否遵循了一定模式等。这样在一定程度上可以强制大家遵守某些约定。自己以前曾经写过一篇文章,请参见这里。

最后要在团队中建立起code review的机制,通过code

review来相互监督纠正命名问题,并且这样更容易达成一致的命名约定,方便协作开发。code

review可以采取非正式会议评审的方式。最简单的方式就是每天找个固定时间大家一起聚在一个显示器前review每个人的代码,现场提出问题,当事人记录下来会后更改。这种方式非常高效。另外有的团队在嵌入代码时可能会引入一些代码评审机制,比如pull

request, cherry pick等。这种review方式比较重量级,反馈周期也较长,好处是可以保证最终迁入的代码是没有问题的。

很多语言和框架为了更加可读,都把命名玩出花来了。比如JavaScript生态圈中重要的单元测试工具Jasmine把测试函数以it命名,这样可以与参数连接起来成为一种表意的自然语言:

如何优雅地为程序中的变量和函数命名?

- 不同的代码段采用不同的命名长度。通常来说,循环计数器(loop

counters)采用1位的单字符来命名,循环判断变量(condition/loop

variables)采用1个单词来命名,方法采用1-2个单词命名,类采用2-3个单词命名,全局变量采用3-4个单词命名。

- 对变量采用具体的命名(specific names)方式,”value”, “equals”,

“data”在任何情况下都不是一种有效的命名方式。

- 采用有意义的命名(meaningful names)。变量的名字必须准确反映它的含义和内容。

- 不要用 o_, obj_, m_ 等前缀命名。变量不需要前缀标签来表示自己是一个变量。

- 遵循公司的变量命名规则,在项目中坚持使用同一种变量命名方式。例如txtUserName, lblUserName,

cmbSchoolType等,否则会对可读性造成影响,而且会令查找/替换工具(find/replace tools)不可用。

- 遵循当前语言的变量命名规则,不要不统一(inconsistently)地使用大/小写字母。例如:userName, UserName,

USER_NAME, m_userName, username, …。

以Java为例:

* 类名使用驼峰命名法(Camel Case):VelocityResponseWriter

* 包名使用小写:com.company.project.ui

* 变量使用首字母小写的驼峰命名法(Mixed Case):studentName

* 常量使用大写:MAX_PARAMETER_COUNT = 100

* 枚举类(enum class)采用驼峰命名法,枚举值(enum values)采用大写。

* 除了常量和枚举值以外,不要使用下划线’_’

- 在同一个类不同的场景(contexts)中不要复用变量名。例如在方法、初始化方法和类中。这样做可以提高可读性和可维护性。

- 不要对不同使用目的的变量使用同一个变量名,而是赋予它们不同的名字。这同样对保持可读性和可维护性很重要。

- 变量名不要使用非ASCII字符(non-ASCII chars)。这样做可能会在跨平台使用时产生问题。

-

不要使用过长的变量名(例如50个字符)。过长的变量名会导致代码丑陋(ugly)和难以阅读(hard-to-read),还可能因为字符限制在某些编译器上存在兼容性问题。

- 仅使用一种自然语言(natural language)来命名变量。例如,同时使用德语和英语来命名变量会导致(理解)不一致和降低可读性。

- 使用有意义的方法名。方法名必须准确表达该方法的行为,在多数情况下以动词(verb)开头。(例如:createPasswordHash)

- 遵循公司的方法命名规则,在项目中坚持使用同一种方法命名方式。例如 getTxtUserName(), getLblUserName(),

isStudentApproved(),否则会对可读性造成影响,而且会令查找/替换工具不可用。

- 遵循当前语言的变量命名规则,不要不统一地使用大/小写字母。例如:getUserName, GetUserName, getusername,

…。

以Java为例:

* 方法使用首字母小写的驼峰命名法:getStudentSchoolType

* 方法参数使用首字母小写的驼峰命名法:setSchoolName(String schoolName)

- 使用有意义的方法参数命名,这样做可以在没有文档的情况下尽量做到“自解释(documentate itself)”

总之,命名问题只是整个编码规范中的一小部分,但是起的作用举足轻重,它是判断一个程序员是否专业的必要标准。