编程如何命名之三:糟糕的命名

jopen 9年前

    在此前的 编程如何命名(一、二)中,分别和大家聊到命名的一些规范,以及作家创作作品和编程的共同之处等话题,今天我们接着聊编程如何命名之三:糟糕的编程命名的特点有哪些,怎么避免。

运用正确意味着每一个词都要用的恰到好处。

编程如何命名之三:糟糕的命名

关于命名 ——菲利普·卡尔顿(Phil Karlton)

计算机科学有两个艰难的事:

  1. 缓存失效 ;
  2. 命名。

关于不好的命名——刘易斯·卡罗尔(Lewis Carroll)

当我使用一个词,胖墩儿说是一种轻蔑,当然这也正是我本事的意思-不多也不少。

爱丽丝奇遇记中,透过镜子,爱丽丝究竟发现了什么?(1871)

故意无意义的名称

理论上讲,foo 仅仅作为一个占位符名称(因为它无任何含义)

编程如何命名之三:糟糕的命名

关于命名——萨姆·加德纳(Sam Gardiner)

“如果你不知道一件事物叫什么,你就不知道它是什么。如果你不知道这是什么,你就不可能坐下来写代码。”

什么是最糟糕的变量名?

——data

什么是更糟糕的变量名?

data2

什么是第三糟糕的变量名?

data_2

编程如何命名之三:糟糕的命名

缩写容易引起歧义

以英文为例, char 是 character(字符) 还是 characteristic(特点)?

mod 的意思是 modify(修改) 还是 modulo (模)?

acc,pos 或者 auth 呢?

另外, fab 只是一个函数,ƒ:A➞B 。

而不是 fabulous (传说)

允许一个例外:ID 作为 “identity” (身份)

一个字母太短 

局部变量:它的含义是什么? 

var a = 42;

这一个是例外:
for  (int  i  =  1;  i  < 42; ++i)

改成 ii,jj,kk 也并不好

函数式编程:一个字母仍然太短

def modp[C](f: B1 => (B2, C), a: A1): (A2, C) = {  val (b, c) = f (get(a))  (set(a, b), c)  }

代码出处:第 70 行

编程如何命名之三:糟糕的命名

编程如何命名之三:糟糕的命名

编程如何命名之三:糟糕的命名

可以用特定含义的词代替更多的词

什么是 appointment_list?

A calendar?日历?

什么是 company_person? 

Employee 普通职员或者是 owner 老板?什么是 text_correction_by_editor?

只是一个 edit-编辑。

模糊语言是模糊的

艾伦·格林写了一些模糊的词,如:

InvoiceManager、TaskManager

Manager’ 非常不准确,其含义之一可能是你想要的字:

Bucket, Supervisor, Planner, Builder

原文地址:点击查看

代码里的模糊用语

get 在方法名的开头只用于返回一个字段值。

如果不是这样,或者从其他地方得到的数据, 用其他的词:

fetch, find, lookup, create, calculate, derive, concoct.

编程如何命名之三:糟糕的命名

错误的词是错的,同义词易混淆

  • order ≠ shipment
  • carrier ≠ broker
  • shipment ≠ transport leg
  • shipment = consignment
  • carrier = transporter
  • transport leg = journey

Java 企业中间件示例 - Apache Camel

JF 杰微刊出品: Apache Camel- http://camel.apache.org

编程如何命名之三:糟糕的命名

编程如何命名之三:糟糕的命名

再探属性访问器 

在许多库中, 这些方法名称将是不可抗拒的,但不建议使用:

  • getEven 
  • getReal 
  • getAround 
  • getRoundTo 
  • getRichQuick 
  • getJoke

糟糕命名的总结 

编程如何命名之三:糟糕的命名

  • 无意义:foo;
  • 太一般:data;
  • 太短:a;
  • 太长:text_correction_by_editor;
  • 缩写:acc;
  • 模糊:InvoiceManager;
  • 错误:order;
  • 只是不好笑:startCamel

如何解决命名问题?以下四个方式供大家参考。

  1. 成为一个更好的作家,
  2. 提高你的词汇量,
  3. 采用更好的命名惯例。
  4. 坚持。

一、成为一个更好的作家

命名只是写作中的一部分,主要跟词汇有关系,你也许记得学习词汇是外语学习的一部分,没有必要学习一门外语真是喜忧参半。

二、提高你的通用词汇量

阅读书籍,尤其是有趣的小说。和总是赢的人玩文字游戏 ,直到他们不再赢。

编程如何命名之三:糟糕的命名

编程如何命名之三:糟糕的命名

使用你的字典和知识库,提高你的通用词汇量。

编程如何命名之三:糟糕的命名

编程如何命名之三:糟糕的命名

“一个三明治走进一家酒吧。酒保说,对不起,我们不招待食物。”

讲笑话

很多笑话都是文字游戏,这需要快速练习双关语,双关语重要的就是命名,因为他们依赖于双重含义,发现双重含义是避免歧义名字的基本技能。

三、采用更好的命名惯例

从含义和意图开始;

使用有精确含义的词语;

喜欢字少的名字;

不使用缩写,除了 ID;

用代码审查来改善命名;

请记住:“重命名”是简单但最有效的重构,请使用它。

用更具体的词替换含糊不清的词:

编程如何命名之三:糟糕的命名

克服重命名恐惧症

比命名更困难的是重命名。

重命名需要变化,会话、新理解。

Refactor 是最安全的重构。

编程如何命名之三:糟糕的命名

第 10 章:变量名的力量

编程如何命名之三:糟糕的命名

第 2 章:有意义的名字

编程如何命名之三:糟糕的命名

第 2 章:命名

  • 学习特定领域的词汇
  • 在维基百科页面搜索领域模型实体的相关概念名称。
  • 阅读客户领域的小说,学习他们的专业术语。
  • 找出他们真正的含义。

编程如何命名之三:糟糕的命名

对于命名,这里有 6 个技巧证明对我很有效:

  1. 花很多时间来创造名字
  2. 使用代码审核
  3. 不要犹豫重命名
  4. 花很多时间在创造名字
  5. 使用代码审核
  6. 不要犹豫重命名 

额外的收益

如果你成为一个更好的作家,你可以使用你的新技能 ——写作。

“大多数的时候,程序员谈论的关于代码里的注释大多数的事情都是他们没写注释的借口。” @PeterHilton

关于注释:基础

  1. 不要说代码是做什么的——因为代码已经说明了 。
  2. 不要解释复杂的逻辑——改进代码使其更加清晰。
  3. 不要添加太多注释——混乱并且会过时。

解释代码为什么存在

即使完美的代码也无法解释它自己为什么存在。

  • 什么时候我该使用这些代码?
  • 什么时候我不该使用这些代码?
  • 有没什么备选的代码,相比这些代码?
  • 发现哪些注释很难写,为什么?

如果注释很容易写,那么说明这些代码不需要注释。

为每个类和方法在开头写一句话注释

“一个常见的谬误是那些不好理解的代码作者如何能在注释里清晰地、明确地表达自己在做什么。”@KevlinHenney

承认编程(注释)是一项专业技能

在一个多功能的开发团队,并不是每个人都擅长视觉设计。写代码亦是如此。找出谁是更好的编程人员。并在写注释方面获得帮助。

如何写出更好的注释(或总结)

  1. 试着先写出好的代码。
  2. 尝试写的一句话的注释。
  3. 重构代码,直到注释写起来简单。
  4. 就是现在写出好的注释。
  5. 不要忘了那些好的写作规则(例如删除不必要的注释)。

四、坚持&总结

  1. 命名是很难的 ;
  2. 多从伟大的作家那得到灵感  ;
  3. 阅读小说,讲笑话,玩游戏  ;
  4. 扩充你的词汇量 ;
  5. 尝试实际写作;

每一个写代码的人,先从写好注释开始,请尝试写博客,甚至是写一本书。

--

译文链接:JF 杰微刊出品

[ 转载请保留原文出处、译者和译文链接。]