优雅代码实践6 之 名副其实

[bingoohuang]

优雅代码实践6 之 名副其实

[bingoohuang]

那一天，我要把生成环境的企业微信登录和测试环境的企业微信登录进行拆分，于是在“企业微信”后台的“应用与小程序”菜单中，新建了一个测试的应用，如下图所示：

然后，我就选取了新建应用的agentId，添加到了获取accessToken的调用api之中。

然鹅，发现问题，测试环境登录好了，生产环境就跪；重启之后，生产环境登录好了，测试环境登录就跪。找啊找啊，终于找到原因了，原来我望文生义，以为accessToken接口中的corpSecret是一个corpId对应一个，因为名字好对应啊，corpId->corpSecret，很像一一对应的样子，结果文档中说得倒是清楚：

我被它的命名欺骗了，corpId->corpSecret，以为“一夫一妻”呢，哪知道是“一夫多妻制”。其实这里，更好命名应该把corpSecret改为agentSecret，因为一个agentId对应一个agentSecret，这样才是名副其实的命名。

[bingoohuang]

逻辑思维第708期 名字为什么很重要？

策划人：耿利杰

和你一起终身学习，这里是罗辑思维。

最近，我和同事闲聊到一个话题，就是十几年前的“冥王星降级”事件。

我们这代人小时候上学，都学过，太阳系有九大行星，最外面的那颗，就是冥王星。这颗星是1930年被发现的。但是，到了2006年，国际天文联合会决定把冥王星从行星里开除出去，降级成一颗矮行星。从此，小学课本就改了，太阳系只剩8大行星了。

这件事情，当时的争论很大。有人就说了，不就是个名字吗？改什么改？不管是行星还是矮行星，冥王星不都是那颗远在几十亿公里之外，围绕着太阳运行的天体吗？不管叫啥，既不改变它本身的属性，也不影响我们对它的观测。好端端的非要改名干啥？我上学背书考试，好不容易学到的知识，你们说改就改了，这是不是你们天文学家在刷存在感呢？

今天就这个话题，跟你聊聊，名字这个东西，真的那么重要吗？先说结论：是的，名字这东西，就真的就这么重要。改和不改，就是不一样。

咱们先来看看“名字”的“名”这个字是怎么来的。名的汉字字形是，上面一个夕阳的夕，就是晚上。下面一个口，说话的口。《说文解字》的解释是：名，自命也。从口夕，夕者，冥也，冥不相见，故以口自名。

一大句古文，我解释一下哈。这句话的意思是说：古人都生活在熟人社会，一个村子规模很小，大家都相互认识。白天，那是不需要什么名字的，大家可以通过长相、动作，判断一个人的身份。但是到了晚上，两眼一抹黑，两个人相见，狭路相逢怎么办？只能靠报出彼此的名字来区分敌我、确认身份了。

你看，命名的本质是什么？是把我们的主观世界客体化的过程。有了这个名字的客体，我们才能展开陌生人的合作。

你想啊，在给一个东西命名前，这个东西的所有特征，都存在于我们的主观世界里。比如，某个人是矮个子、长头发、黑脸膛、跑得快、爹是谁、亲戚是谁等等。这是一大坨乱七八糟的特征，既没有秩序，也无法穷尽。当我们共同说起一个人的时候，说半天也说不清楚是不是同一个人。而一旦我们给他起了个名字，比如用“张三”来称呼他，就相当于把一大组特征，打了个包，投射到了这个名字上。大家都公认，这个人是张三，这就可以讨论了。至于对他的各自的主观印象，各自想各自的，不一致也不要紧。

所以名字，可不是什么虚拟的东西，仅仅是个符号。不，它是一种客观实在，而且是人类社会，陌生人大规模合作中最重要的客观实在。

《百年孤独》开篇有一句经典的话，是这么说的：世界新生伊始，许多事物还没有名字，提到的时候尚需用手指指点点。

设想一下当时的情景：因为所有的东西都没有被命名，外部世界就是混沌一片。什么可以信赖，什么不可信赖，哪些安全，哪些危险，所有这些都无从得知。这个阶段，人们对于外部世界的认识，一定非常有限。怎么办？命名嘛。只有不断给事物命名分类，外部世界才能从混沌变得可知。

这样说可能有点抽象，我再举个例子，就说天上飞的鸟吧。刚开始的时候，我们把所有带羽毛、会飞的的都叫“鸟”。但是你想，鸟在天上飞，人是抓不住的，想深入研究是不可能的。那怎么办？分类啊，命名啊。门纲目科属种，这么一路命名下去，结果是啥？

结果是，一个鸟类学家，站在地上看一眼天上，就能分清楚飞过的这是个什么鸟。比如一只鸟，背部和面部的羽毛颜色是翠蓝发亮、爪子呢是赤红色的，嘴形是又长又尖，而且又是在水边发现的它，这几个简单的信息，鸟类学家就可以做出判断了：翠鸟。如果这鸟眼睛上边的羽毛是蓝色，而不是橙黄色的，那还能进一步判断——斑头大翠鸟。你看，鸟类学家不用真的把这只鸟捉到，观察它的所有细节，就已经可以开始认知和研究。人们对于鸟的认知水平，一下子就上去了。所以有人说，学科进步的第一步就是命名。

事实上，有些伟大的科学进步，本身就是命名。比如，提出“熵”这个概念，这就是对一组现象的命名啊。仅仅提出这个概念，就已经是科学的重大进展。

文化人类学上有一个有趣的发现，各个民族的神话都有一条通行的规则——妖魔鬼怪出现时，如果你能叫出它的名字，它的魔力就会减损大半，甚至完全丧失。反过来，如果你被对方叫出了名字，你的力量也会化为乌有。回想一下《西游记》，好像就有这样的情节。妖怪叫孙悟空“孙行者”时，他是一定不能答应的，一旦答应就要被收服。

你看，这就是名字的作用。只有给对方命名，叫出对方的名字，才能把它从混沌的外部世界分割开，单独召唤到我们面前，它才能被我们认识。

还不仅仅是认识这么简单。名字既然是一个实体，它对现实世界就一定也有反作用。

举个例子，我曾经看过一个研究，对比**和西方国家的禁毒工作。结果就发现，很多国家禁毒的效果比**差得远。这当然是很多因素共同作用的结果。但那篇文章，还提到了很有趣的一点，就是汉语和英语里对毒品的叫法不同。你看啊，汉语里，毒品被称为“毒”，毒药的毒，一听就给人这东西有害、要远离的感觉；而英语里，毒品的叫法是drug，药品，单纯的中性词，就没有特别的暗示。你看，同样的东西，名字不同、叫法不一样、给人的感觉不同，就会影响了人们对它的态度。

好，理解了命名的这些作用，我们再说回到开头提到的那个问题，冥王星为什么要改名？不叫行星了，而叫矮行星？

天文学家朱惠特说：这非但不是“矮化”，反而是冥王星的“升迁”。

你就想啊，过去冥王星被当作行星的时候，冥王星特别不起眼，因为小，体积只有月球的三分之一，质量只有月球的六分之一。而且又离我们那么远，观测起来那么费劲，所以注定是要被忽视的嘛。一点存在感都没有。

但是现在冥王星的命运，它被开除出行星了，变成矮行星。结果是啥？结果是，现在只要你要讲太阳系的行星，最后一定得专门把冥王星拿出来讲一讲。你说它的地位是不是重要多了？

再从天文学的内部来看，专门划出一类天体叫“矮行星”，这意味着啥？意味着更多的人力资源和科研经费，当然会有新的研究成果出现，又会吸引更多的注意力。

果不其然，2006年它被开除的，2008年6月11日，国际天文联合会给海王星以外的矮行星们，起了个名字，统一叫“类冥天体”，就是和冥王星类似的天体。冥王星直接变成这一区域的老大哥，成为附近这类天体的模板了啊。

你看一下这个过程吧，改名之前，冥王星只是一颗孤悬于外太阳系的、畸形的、渺小的、注定要被忽视的奇异天体，丑小鸭一只；而现在，它变成了那个区域的老大哥，被从遥远的外太阳系，重新召唤到了我们面前，获得了无数的额外关注，摇身一变成了白天鹅。

你看，我们熟悉的丑小鸭的故事，不就是一个命名错的故事么？

你就说，这是降级还是升迁？所以说啊，让我们祝贺冥王星吧。

从这个故事里，我们可以再次洞察到名字这个东西的重要性。它不是什么任意的符号。它是一个东西在人类世界里的再一次出生，它还是一个东西放大自己价值的最好杠杆。

[bingoohuang]

Codelf(变量命名神器)

[bingoohuang]

Kendrick Lamar说过：

如果我要讲一个真实的故事，那么一定是从故事的命名开始。
If I’m gonna tell a real story, I’m gonna start with my name

命名会遍布代码的每一个角落，我们会为函数、类、参数、包等命名，还会为源文件、目录命名。总之，在写代码的过程中，好的命名可能是使代码变整洁的最重要的因素。

你的命名应该显示出你的意图。选择一个好的名称会耗费你的一些时间，但是如果随意命名，以后你会浪费更多的时间来理解它。所以请尽可能使你的命名更加合理，读你的代码的人也会因此感谢你。

你要谨记的是，变量、函数和类的命名应该能回答三个问题：它为什么存在、它是做什么的、它用在哪里。

这不仅需要良好的描述能力，还需要了解跨国界的文化背景。要教会你这些，没有人能比你自己更合适了。

什么才是优秀的代码

[bingoohuang]

看了一段电子合同里面的代码，应该说优点是，注释写得非常清晰，美中不足的是命名与注释不能前后呼应。

  /** 左右偏移量，正数向右偏移，负数向左偏移 */
  @ApiModelProperty(value = "左右偏移量，正数向右偏移，负数向左偏移")
  private Integer moveSize;

  /** 上下偏移量，正数向上偏移，负数向下偏移 */
  @ApiModelProperty(value = "上下偏移量，正数向上偏移，负数向下偏移")
  private Integer heightMoveSize;

所谓，不能“前后呼应”，意思，就是，没看到注释之前，只看变量名称：moveSize不能准确地意会到是左右偏移量, heightMoveSize还稍微好点，说明是与高度相关的移动大小。

命名，实际上是编程设计中最基本的动作。从命名的角度来看，也足以看出一个人的编程水平在什么层次。

逻辑思维里，有一章就是说命名的：

文化人类学上有一个有趣的发现，各个民族的神话都有一条通行的规则——妖魔鬼怪出现时，如果你能叫出它的名字，它的魔力就会减损大半，甚至完全丧失。反过来，如果你被对方叫出了名字，你的力量也会化为乌有。回想一下《西游记》，好像就有这样的情节。妖怪叫孙悟空“孙行者”时，他是一定不能答应的，一旦答应就要被收服。

所以，如果要名副其实，也就是注释与命名前后呼应的话，上面的两个命令其实可以有更好的选择：

  /** 左右偏移量，正数向右偏移，负数向左偏移 */
  @ApiModelProperty(value = "左右偏移量，正数向右偏移，负数向左偏移")
  private Integer horizontalOffset;

  /** 上下偏移量，正数向上偏移，负数向下偏移 */
  @ApiModelProperty(value = "上下偏移量，正数向上偏移，负数向下偏移")
  private Integer verticalOffset;

对啦，左右的英文是horizontal，偏移量的英文是offset，上下的英文是vertical，这样的命名，才是真正的名副其实，才能让人“望文生义”，多好，不需要再次点击进来看注释了，本身就“文如其人”了，读代码的时候就很顺畅了。

这时候，我想一定有人会说，英文我没学好哎，不知道左右的英文是horizontal，也不知道上下的英文是vertical，更不知道偏移量的英文是offset，但是就是入了IT这行，还进了同一个项目组，还要每天码代码，咋整呢？

不急不急，其实，我也不懂，我都是现用现查，经常看看别人怎么写的。

[bingoohuang]

67岁的老奶奶ROBIN WILLIAMS 在她的书《写给大家看的设计书》的开头小故事，约书亚树

很多年前的一个圣诞节，我收到一份圣诞礼物，是一本关于如何认识各种树的书。当时我住在父母家，所有礼物都打开后，我决定出去走走，认一认邻居家的树。出去之前我读了书的一部分。其中提到的第一种树是约书亚树，只需要两个线索就能认出它。由于约书亚树相当怪异，所以看到书中它的照片时，我对自己说：“哦，北加利福尼亚绝对没有这种树。这种树太怪异了。如果我见过，肯定应该有印象，可我以前从来没有见过。”

之后我拿着这本书走出家门。我的父母住在一个小巷子里，这里共有 6 家住户。其中 4 家的前院里都赫然立着约书亚树。我住在那里已经有 13 年 了，此前居然从未注意过约书亚树。我在这个街区转了转，发现似乎每一家布置新居时都会到苗圃买约书亚树，至少 80% 的住家前院都种有约书亚树。而我在此之前居然从来没有注意过！在我知道了这种树之后，我是说在我能够说出它的名字后，它就无处不在了。这正是我要强调的：一旦能够说出什么东西的名字，就会很容易注意到它。你就会掌握它，拥有它，让它受你所控。

写给大家看的设计书（第4版）.pdf

[bingoohuang]

GO语言贡献者的第一步：提交命名的修正

来自How to write a self hosted Go compiler from scratch Daisuke Kashiwagi Gophercon 2020 November 12

Official compiler: variable names for slice

// note this is the runtime representation
// of the compilers arrays.
//
// typedef struct
// {
// uchar array[8]; // pointer to data
// uchar nel[4]; // number of elements
// uchar cap[4]; // allocated number of elements
// } Array;
var array_array int // runtime offsetof(Array,array) - same for String
var array_nel int // runtime offsetof(Array,nel) - same for String
var array_cap int // runtime offsetof(Array,cap)
var sizeof_Array int // runtime sizeof(Array)

Could we improve these ?

1. “array” → “slice”
2. Tried Gerrit

Merged 🎉,It’s in Go 1.4