代码里的命名规则:错误的和正确的对比

编程初学者总是把大量的时间用在学习编程语言,语法,技巧和编程工具的使用上。他们认为,如果掌握了这些技术技巧,他们就能成为不错的程序员。然而,计算机编程的目的并不是关于精通这些技术、工具的,它是关于针对特定领域里的特定问题创造出相应的解决方案,程序员通过相互合作来实现这些。所以,很重要的一点,你需要能精确的用代码表达出你的思想,让其他人通过代码能明白你的意图。

代码里的命名规则:错误的和正确的对比

让我们先看看编程大师Robert C. Martin的杰作《Clean Code | 代码整洁之道》里的一句话:

“注释的目的是为了弥补代码自身在表达上的不足。”

这句话可以简单的理解为如果你的代码需要注释,最有可能是你的代码写的很烂。同样,如果在没有注释的情况下你无法用代码完整的表达你对一个问题或一个算法的思路,那这就是一个失败的信号。最终,这意味着你需要用注释来阐明一部分的思想,而这部分在代码里是看不出来的。好的代码能够让任何人在不需要任何注释的情况下看懂。好的编码风格能将所有有助于理解这个问题的所有信息都蕴含在代码里。

在编程理论中,有一个概念叫做“自我描述的源代码”。对于一段代码,一种常见的自我描述机制是遵循某种非严格定义的变量、方法、对象命名规则。这样做的主要作用就是使源代码更易读易懂。所以,也就更容易维护和扩展。

这篇文章里,我将举出一些例子,说明什么是“不好的代码”,什么是“清楚的代码”

命名要能揭示意图

如何命名,在编程中这永远都是个老大难问题。有些程序员喜欢简化、缩短或加密名称,使得只有他们自己能懂。下面让我们看一些例子:

不好的代码:

“d”可以表示任何东西。作者使用注释来表明他的意图,却没有选择用代码来表示。而“faid”很容易导致误解为ID。

清楚的代码:

命名时避免含义引起误解的信息

错误的信息比没有信息更糟糕。有些程序员喜欢“隐藏”一些重要信息,有时候他们也会写出一些让人误解的代码。

不好的代码:

变量“customerList”其实不是个list。它是一个普通的array(或客户集合)。除此之外,“theTable”是一个Table类型的对象(你可以用IDE容易的发现它的类型),“the”这个词是个不必要的干扰。

清楚的代码:

命名要有合适的长度

在高级编程语言中,变量名的长度通常不太限制。变量名几乎可以任何长度。虽然如此,这也可能使代码变得闹心。

不好的代码:

好的名称应该只含有必要的词汇来表达一个概念。任何不必要的字词都会使名称变长、难于理解。名称越短越好,前提是能在上下文中表达完整的意思(下订单这个场景中,“customersInOrder” 要比 “list” 好)。

清楚的代码:

命名时编码规范保持一致,让规范帮助理解代码

所有的编程技术(语言)都有自己的“风格”,叫做编码规范。程序员应该在写代码时遵循这些习惯,因为其他的程序员也知道这些,并按这种风格编写。下面我们看一个没有明显规范的不好的代码例子。下面的这段代码没有遵循很好的已知的“编码规范”(比如PascalCase, camelCase, Hungarian规范)。更糟糕的是,这有一个毫无意义的bool变量“change”。这是个动词(用来描述动作),但这里的bool值是来描述一个状态,所以,这里应该用一个形容词更合适。

不好的代码:

一段代码,只看它的一部分,你就应该直接明白它是什么类型,只需要看它的命名方法。

例如:你看到了“_name”,你就能知道它是个私有变量。你应该在任何地方都利用这种表示方法,没有例外情况。

清楚的代码:

命名时相同的概念用相同的词表达

定义概念很难。在软件开发过程中,很多时间都花在分析业务场景、思考正确的定义里面所有的元素。这些概念永远都是让程序员头痛的事。

不好的代码:

首先:

代码的作者试图表达“get the data”的概念,他使用了多个词“load”,“getch”,“get”。一个概念只用一个词表达就行了(在同一个场景中)。

第二:

“set”这个词用在了2个概念里:第一是“data loading to view”,第二个是“setting a value of object”。这是两个不同的概念,你应该使用不同的词。

清楚的代码:

命名时使用跟业务领域相关的词

程序员写的所有代码都是跟业务领域场景逻辑相连的。为了让所有关系到这个问题的人都能更好的理解,程序中应该使用在领域环境中有意义的名称。

不好的代码:

当在编写针对某个领域的代码时,你应该始终考虑使用领域有联系的名称。在将来,当另外一个人(不仅是程序员,也许是测试人员)接触你的代码时,他能轻松的理解这个业务领域里你的代码是什么意思(不需要业务逻辑知识)。你首先考虑的应该是业务问题,之后才是如何解决。

清楚的代码:

命名时使用在特定环境里有意义的词

代码里名称都有自己的上下文。上下文对于理解一个名称非常重要,因为它能提供额外的信息。让我们来看看一个典型的“地址”上下文:

不好的代码:

在大多数情况中,“Post Code”通常是地址的一部分,很显然,邮政编码不能单独使用(除非你是在开发一个专门处理邮编的应用)。所以,没有必要在“PostCode”的前面加上“address”。更重要的,所以的这些信息都有一个上下文容环境,一个命名空间,一个类。

在面向对象编程中,这里应该用一个“Address”类来表达这个地址信息。

清楚的代码:

命名方法总结

概述起来,做为一个程序员,你应该:

  • 命名是来表达概念的
  • 注意名称长度,名称里只该含有必要的词语
  • 编码规范有助于理解代码,你应该使用它
  • 名称不要混用
  • 名称在业务领域里要有意义,在上下文里有意义
收藏 9 评论

相关文章

可能感兴趣的话题



直接登录
最新评论
  • thoupin   2013/06/07

    其实这些在 Code Complete(2nd) 里都有,这本书不错的,建议各位逛伯乐的朋友, 如果没看过都去看看。

  • 文章的开头很差,不但有误导倾向,而且对下文的衔接做得不好。

    • 好吧,我阅读失误……囧

      • zqq90   2013/06/09

        如果一个人失误 很正常
        但是两个人同时“失误”。。我想就是文章的问题了
        “好的文章能够让任何人在不需要看任何评论的情况下看懂”

    • 黄余粮 站长 2013/06/09

      作者在文中开头要表达:尽量用清晰的代码,而不是依靠注释来解释。接着,文章列举了清晰的代码和表述不清的代码 (意思是需要加注释的代码,虽然没有明确这样说)。因为没有直接提到注释,直观上给人的感觉是开始说注释,后面只字不提,直观上确实感觉有些衔接的不太好。

  • zqq90   2013/06/09

    -1. 看来我写了很多“烂代码”

    0.原文很多评论 大家自己看
    个人觉得本文是对注释的偏见
    不能滥用注释 但是也不能没有注释

    1. 包含功能性的注释不可缺
    //TODO:
    //NOTE:
    //FIXME:
    //DOC:

    2. 对功能模块的注释可以让我们不读代码就能知道大段代码什么意思,代码不只是用来欣赏的,更要讲求团队合作的效率,都注释总比翻译代码来得简单

    4. 水平参差不齐 如何解释“任何人”,如果“任何人”都能像编译器一样 正确的知道每段代码的意思 我想就解决贫富差距了

    5. 母语非英文的表示压力很大呀

    文章断章取义 把变量命名规则 的原则 强加到注释 误导极大呀
    PS: 文章作者貌似是 ".NET developer " 你让其他语言怎么看

    • zqq90   2013/06/09

      补充:

      “注释的目的是为了弥补代码自身在表达上的不足。”
      不等于
      “如果你的代码需要注释,最有可能是你的代码写的很烂”

      “表达不足” 是难免的 并不只是“很烂”
      代码本来就表达不足 代码 不是人类的第一语言 不是人类沟通的语言

    • 黄余粮 站长 2013/06/09

      文章断章取义 把变量命名规则 的原则 强加到注释 误导极大呀

      --  赞同!文章主体是在讲命名规则。用命名规则的例子去推倒注释,我也认为没有说服力。

跳到底部
返回顶部