最近进行了三菱m80机床解锁感觉很有收获，现在结合自己的理解再来总结编写可读性代码的技巧，会用 js 举例，并且针对日常开发中常见的代码异味给出改我的进建议。

学会该书的大部分技巧并付诸实践，不能保证保证你写出完美的代码，但是能保证你写出能读的代码，保证你的码德下限。

可读性 = 可测试性 = 设计良好 = 可维护 = 代码质量 = …，衡量代码的各种指标，都是正相关的，开发程序的大部分时间是在阅读代码（自己的和他人的），所以保证了可读性，其他指标也不会差。

衡量代码的可读性 大部分程序员，全靠自觉、灵感和经验编写代码，往往很难一步到位写出可读性高的代码。

我看过一些前端组长(猪长)、前端架构师(加狗屎)写的代码，简直惨不忍睹，让人有骂娘的冲动。

比如这种：

除了手写 render 函数，毫无可读性之外，行宽过大，编辑器都出现滚动条了，也会让人不想读。

不可读的代码往往都会有这样或那样的问题。

软件的成本由开发成本和维护成本组成，而往往维护成本要远高于开发成本，维护成本主要花在理解代码和修改代码上，可读性高、设计良好的代码可大大降理解和修改代码的成本。 可见代码的可读性至关重要。

如何衡量代码的可读性呢？ 代码可读性和代码被他人理解的时间成正比，即他人理解代码的时间越少，可读性越高。 如何定义他人？根据我的经验，高年级本科生或者研究生或者工作 2 年内的程序员，又或者，你的一个普通同事。

同事是和你协作的人，让和你协作的人能快速地理解你的代码，至关重要。 如何定义理解？ 理解是一个非常高的标准。真正理解了，就应该能改动它、找出缺陷且明白它与外部代码交互的规则。

可读性的标准可以降低吗？ 当可读性和其他约束条件冲突时，比如性能、代码行数，如何取舍？

大部分情况，可读性优先，那些可能会经常被他人阅读、改动的代码，可读性再怎么强调都不为过。 编写可读性的代码很难吗？ 编写可读性高的代码很难。如果一个程序员放弃了可读性这一目标，那么他一定不会成为更好的程序员。 编写可读性高的代码，前人已经总结了诸多技巧和经验，学习并实践这些经验，可以让代码的可读性不至于很糟糕。

命名的技巧 好的代码，从好的命名开始。

把信息放在名字里 选择专业的词汇，使得意思更加清晰和精确。 比如 fetchData 比 getData 好；

单词 更多的选择 send deliver、dispatch(派发)、announce(声明)、distribute(分配、广播)、route(按照指定路径投送) find search、extract(提取)、locate(定位)、recover(还原) start launch、create(创建)、begin、open make create、setup(就绪)、build、generate(生成)、compose、add、new 技巧：如果存在两个相对或者相反的操作，取名使最好能让他人知道一个，便能直接的猜到有一个操作。 start 和 stop 相对， pause 和 resume 相对。

技巧：取名符合生活或者数学的习惯。比如 count 一般为正数, num 使可正可负， complexNumber 复数。 避免宽泛的名字，除非有特别的理由 避免使用 tmp 、 retval 这类宽泛的名字。好的名字应该描述变量的目的或者它承载的值， tmp_file 比如 tmp 好。

const euclidean_norm = arr => { let retval = 0 for (let i = 0 i < arr.length; i++) { retval += arr[i] * arr[i] } return Math.sqrt(retval) } 这函数在累加数组中元素的平方，把 retval 改成 sum_squares 更好。

sum_squares 包含它的目的，如果累加代码不小心写成 retval += arr[i] ，就非常容易发现缺陷。

使用 tmp、it 和 retval 等这些空范的名字时，你需要有足够好的理由。

使用具体的名字，避免抽象的名字 力求把实体描述得更具体，而非抽象，越具体，会越明确。 serverCanStart() 没有 canListenOnPort 具体。

技巧：名字里名字和形容词时，会比较具体。感觉不够具体时，不妨加入名字和形容词。 使用前缀或者后缀把重要的信息附加到名字上 常见的可以附加的信息： ① 单位

函数参数 参数带单位 start(delay) delay -> delay_secs createCache(size) size -> size_mb throttleDownload(limit) limit -> max_kbps rotate(angle) angle -> degrees_cw angle 角度，单位度。cw(circular_measure)，弧度。 在一个项目遇到一个函数的参数对象属性为 rotate :

someFunction({ rotate: rotate_value }) 它接收一个从后台接口返回的值，采用的单位是度，产品经理一直说不对，但是我们也找不到问题，就把这个问题放了很久。产品经理有一天又去找人确认是否正确，给的答复没问题。 产品又来找我，说那边反馈数据对的。我才猛然想到采用的单位是不是弧度，于是我把角度转成了弧度，产品就说对了。如果给属性加上单位，那么就一眼看出来了。

我们这个项目还涉及角度的方向，最后几经测试，需要做两件事情：角度转为弧度；三维地图下，旋转方向为逆时针。

把单位加入参数。

someFunction({ route_cw: cw_value // 顺时针的弧度 anticlockwise/counterclockwise 逆时针 }) 如果把三维地图下逆时针也加入，参数就长了，选择不加，可通过函数注释的方式告知使用者。 ② 变量存在危险或者意外

情形 变量 更好的选择 纯文本的密码 password plaintext_password 用户提供的注释，需要转义后才能显示 comment unescaped_comment 安全的 html 代码 html html_safe\ html_escaped 变量作用域大小决定名字长短 小作用域，使用段名字，大作用域，使用长名字。 const numList = [1, 2, 3] let sum = 0 for (let i = 0; i < array.length; i++) { sum += array[i]; } i 的作用域很小，即使取名很短，也一眼能看出它的目的。 再看一例：

for (i = 0; i < clubs.size(); i++) { for (j = 0; j < clubs[i].members.size(); j++) { for (k = 0; k < users.size(); k++) { // do something } } } i j k 的作用域也很小，但是这里涉及到多层嵌套，当嵌套里操作复杂时，就很容易混淆它们，此时可以适当让各自的下标变长，以做区分。 for (club_i = 0; club_i < clubs.size(); club_i++) { for (member_i = 0; member_i < clubs[club_i].members.size(); member_i++) { for (user_i = 0; user_i < users.size(); user_i++) { // do something } } } 长名字不好打，而不使用？ 有人会因为长名字需要输入更多字符而不想使用，现在而 IDE、AI 编程助手已经能自动补全了，不存在这个问题。

避免随意缩写，造单词。 随意缩写很让人费解。

技巧：开启编辑器拼写检查，可防止写错单词。 众所周知的缩写是可以使用的，比如

button -> btn background -> bg backgroundColor -> bgColor image -> img document -> doc string -> str number -> num evaluation -> eval index -> i column -> col hexadecimal -> hex binary -> bin octal -> oct # 八进制 decimal -> dec # 十进制 to -> 2 # to 在中间可，可缩写为 2, 比如 bin2dec 二进制转为十进制 address -> addr application -> app average -> avg # 平均数 command -> cmd organization -> org # 组织 original -> orig destination -> dest/des resource -> res # 资源 source -> src # 源数据 ascending -> asc # 升序 descending -> desc # 降序 device -> dev # 设备 different -> diff # 区别 directory -> dir # 目录 environment -> env # 环境 error -> err library -> lib # 库 information -> info # 信息 message -> msg number -> num object -> obj parameter -> param parameters -> params # 实参 参数 arguments -> args # 实参 参数 argument -> arg # 形参 参数 package -> pkg # 包 n 打包 v position -> pos # 位置 configuration -> config # 配置 array -> arr previous -> pre next -> next middle -> mid # 中间 current -> cur # 当前的 password -> pwd reference -> ref summation -> sum system -> sys # 系统 temporary -> temp # 临时 或者 tmp text -> txt # 纯文本 variable -> var character -> char status -> stat # 状态 standard -> std # 标准 trigger -> trig # 触发 user -> usr # 用户 length -> len # 长度 administrator -> adm # 管理员 database -> db # 数据库 coordinates -> coord # 坐标 longitude -> lng # 经度 latitude -> lat # 维度 angle -> ng # 角度 circularMeasure -> cw # 弧度 dictionary -> dic # 字典 link -> lnk # 链接 window -> win/wnd # 窗口 horizontal -> horz # 水平 public -> pub

delete -> del decrease -> desc # 减少 increase -> inc # 增加 increment -> inc # 增加 execute -> exec # 执行 maximum -> max # 最大 minimum -> min # 最小 calculate -> calc initialization -> init # 初始化的 initialize -> init # 初始化 generate -> gen # 生成 synchronization -> sync asynchronization -> async control -> ctr # 控制 escape -> esc # 退出 insert -> ins # 插入 extend -> ex/ext # 扩展 vertical -> vert # 垂直 instance -> ins # 实例 multiply -> mul # 乘 禁止拼音缩写 拼写的缩写意思很多。

shuBen -> sb

jiaGe -> jg

使用缩写的经验法则：当新成员能理解这个缩写时，即可使用。

删除没用的词

拿掉某个词，不会损失信息，就删除它。 比如

convertToStr -> toStr # 意思一样 doStop -> stop # 有多个意思一样的动词，往往只需保留一个。

使用格式表示含义 把特定的格式放在变量里，使得一眼能看出不同变量的区别。 常用的格式有： _ 、 - 、 # 、 $ 和 大小写 等。

const YYYYMMDD = ‘2023-03-23’ // 这个变量，就能一眼推断出表示一个时间 遵循编程语言或者团队的约定，且保持一致。 对前端来说，构造函数使用大坨峰(PascalCase/UpperCamelCase)，普通函数使用小驼峰(lowerCamelCase)。

const person = new Person() const age = getAge() jquery 对象使用 $ 开头，事件处理器使用 onXxx 或者 handleXxx

技巧： onXxx 作为属性或者参数，而 handleXxx 作为函数，会更好。 const $allImages = $(‘img’) DOM 的 ID 属性值使用 _ 连接，类名使用 - 或者 – 。

vue 和 react 组件中： _ref 表示模板引用：

const div_ref = ref() // 表示引用一个 div const com_ref = ref() // 表示引用一个 组件 不要使用有歧义的名字 名字容易歧义吗？当命名时，多问问自己，主动找到可能歧义的词语。 filter 就是一样容易有歧义的词语，可以是挑出一些，也可以是删除一些，剩下一些。

用 min 和 max 表示极限 const CART_TOO_BIG_LIMIT = 10 // 购物车最多10个物品 const MAX_ITEMS_IN_CART = 10 // ✅ better 用 first 和 last 表示包含末尾 const str = ‘abcd’ // first = 0 last = 3 包含 d 用 start/begin 和 end 表示不包含末尾 const str = ‘abcd’ // start = 0 end = 3 不包含 d 更好地给变量加否定前缀 英文中表示否定前缀的有很多，比如 un 、 de 、 dis ，如何选择呢？

前缀 后缀 描述 例子 non 名词、动词、形容词 表相反的意思 editedRows->nonEditedRows de 动词 表相反的动作 encodeURIComponent->decodeURIComponent un able 结尾的形容词或者一动词 founded->unfounded known -> unknown non 最通用，搞不清楚，一律 non 就行了。

参考: How to Use the Prefixes “Dis” and “Un” Correctly

给布尔变量命名 当命名布尔变量或者返回布尔值的函数命名时，要确保阅读者一眼明确(返回)值的范围是 true 或者 false 。

const read_password = true // bad ❌ 两种理解：1. 读取密码，动作 2. 已经读取了密码 const need_password = true // ok 👌 const has_password = true // best ✅ const edit = true // bad ❌ const shouldEdit = true // ok 👌 const enableEdit = true // better 😄 const canEdit = true // best ✅ 通过使用 is 、 can 、 should 、 enable 和 has 前缀或包含表示布尔变量。 这些词在英语中常常使用来引导疑问句，而疑问句的回答一般是 yes 或者 no ，对应 true 或者 false 。

前缀 常见的搭配 描述 例子 补充 is is + 形容词 是否具备某种属性或者状态 isOk、isHidden 单独的形容词，也能猜到是布尔变量，但是不够明确，比如 hidden、sortable is is + 动词过去式 是否完成了某个动作或者某件事 isConnected、isFilled、isSorted is is + 名词 是否是某个东西 isAdmin、isVIP、isEditing、isProUser has has + 名字 是否存在某物 hasKey、hasError、hasOnlineUser 名字一般使用单数，复数也无伤大雅 can can + 动词原型 是否启用某种能力 使其具备某种功能 canEdit、canRemove enable enable + 动词原型 是否启用某种能力 使其具备某种功能 enableEdit、enableLoad 还能用于命名函数 should should + 动词原型 是否执行某个操作，一般用于命名函数 shouldRemoveBlank、shouldFillTable 不关注数量。全部、所有，使用 every 或者 each, 比如 isEachUserActive，isEveryOrderClosed，存在至少一个，搭配 some、any 或者 has, 比如 isSomeUserLogin、isAnyUserOnLine、hasOnlineUser。