How to write high quality JS function (2) - name / comment / piece robust

This article first appeared in vivo micro-channel public number of Internet technology 
links:https://mp.weixin.qq.com/s/sd2oX0Z\_cMY8\_GvFg8pO4Q
Author: Yang Kun

Part I , "how to write high quality JS function (1) - Qiaoshanzhenhu chapter," describes the function of the enforcement mechanism, this post will be from naming, comments and robustness in terms of function, it describes how to write high quality JS function.

(A) function name

First, the current front-end function naming any problems exist

From the graph you can see, name and cache are two major problems in computer science.

This article saying the function name, although related to the scope is narrow, but the idea is the same, can learn from the other forms.

Prior to read the relevant sections of code complete variables, but also targeted to find out about some of the source code, summed up my experience, the current function name in addition to industry-standard issues, there are still some details of the problem, such as:

• Differences in the English word

• Do not know how to upgrade from a multi-dimensional named accuracy (how to upgrade from a multi-dimensional accuracy named)

• Do not use aids (how to use the aids)

Concise analysis below.

Second, the differences in Chinese and English

1, Why not be named in Chinese way of doing things?

Hanyu Pinyin there is ambiguity; kanji translation aid is not enough popular, and therefore can not be named in Chinese way.

2, the difficulties encountered in English

The biggest difficulty is that correct grammar usage scenarios.

For example, the life cycle of REACT, as follows:

• componentDidMount

• componentWillReceiveProps

• shouldComponentUpdate

Many people will have questions, Why did and will.

Third, how to make name in English style

for example:

• componentDidMount hook react and so is the life cycle, but why this name?

• componentWillReceiveProps Why this name?

The answer to the following figure:

注意上图中的 did 代表一般过去时，will 代表一般将来时。

然后我们百科一般过去式和一般将来时，如图所示。

（1）一般过去时：

（2）一般将来时：

看上图的红箭头，did 表示一般过去时，时是指动作发生的时间，用在这里，突出了钩子的含义，一旦 mount 成功就执行此函数。will 同理。

四、通过函数返回结果来命名

这是个小特性，比如 shouldComponentUpdate ， 为什么 should 放在最前面。

因为这个函数返回的值是布尔值。那么我们可以理解为这是个问句，通过问句的形式来告诉我们，这里具有不确定性，需要根据返回值来判断是否更新。

五、借助工具

1、借助谷歌翻译

2、借助 codelf

这是一个神器，用来搜索各种开源项目中的变量命名，以供参考。

地址：unbug.github.io/codelf/

对应名字的 VSCODE 插件也有。

六、如何避免函数命名的多义性和不可读性

ramda 源码中的一个函数，代码如下：

var forEachObjIndexed = _curry2(function forEachObjIndexed(fn, obj) {
var keyList = keys(obj);
var idx = 0;
while (idx < keyList.length) {
var key = keyList[idx];
fn(obj[key], key, obj);
idx += 1;
}
return obj;
});
export default forEachObjIndexed;

这个函数叫 forEachObjIndexed ，代码中看不出这个函数的命名含义，只能从从源码里面的函数注释中找答案。

函数注释如下图：

由此知道，如果函数命名存在困难，可以通过注释的方式，将函数的整体介绍和说明输出文档来解决这个问题。

七、函数命名的分类

函数命名很普遍的一个现象就是带各种前缀的函数名，如下：

- $xxx()
- _xxx()

这种带各种前缀的函数名，看起来并不好看还别扭。核心原因是 JS 语言不支持私有变量，导致只能使用 _ 或者 $ 来保证相应的对外不可**见。**

所以我把前端的函数命名分为两大类，如下：

第一类：不想暴露给外部访问的函数(比如只给内部使用)

第二类：暴露给外部访问的函数(各种功能方法)

 而Symbol 初始化的函数命名是一种特例，代码如下：​​​​​​

const ADD = Symbol('add')

[ADD](a, b) {
console.log('a + b')
}

八、总结

总结一下最佳实践：

多学习初中高中英语语法，开源项目中的函数命名没有那么难理解，通过语法的学习和借助工具，函数命名基本可以解决，如果遇到无法清晰描述所写函数的目的的命名时，请务必给函数写上良好注释，不管函数名字有多长多难懂，只要有良好的注释，那就是可以接受的一件事情。

（二）函数的注释

一、有名的npm包的一些注释风格

函数注释，一方面提高了可读性，另一方面还可以生成在线文档。

一个高质量的函数，注释少不了，但是这并不代表所有的函数都需要注释。富有富的活法，穷有穷的潇洒，重要或者复杂的函数，可以写个好注释；简单或者不重要的函数，可以不写注释或者写一个简单的注释。

那么，目前函数的注释都有哪几种方式呢？

1、egg.js 的注释风格

从图中可以看到 egg.js 的入口文件的注释特点是简单整洁。

继续看下图：

这是一个被抽象出来的基类，展示了作者 [Yiyu He] 当时写这个类的时候，其注释的风格有以下几点：

第一点：构造函数的注释规则，表达式语句的注释规则。

第二点：注释的取舍，有一些变量可以不用注释，有些要注释，不要有那种要注释就要全部注释的思想。

再看两张有趣的图片：

看上面两张图的箭头，指向的都是同一个作者 [fengmk2] 。他的函数注释规则，第一张图没有空格，第二种有空格，还有对返回的 this 的注释，比如很多人习惯将 this 直接注释成 Object 类型。

2、lodash.js

说到函数注释，就不能不说到 lodash.js 。由于篇幅有限，本文就不做相应介绍了，大家自行按照上面的方式去了解。

二、通过注释生成在线文档的思考

有人说注释要很规范，方便给别人，比如用 jsdoc 等 。我的观点是，对一些不需要开源的 web 项目，没有必要用 jsdoc ， 理由如下：

1.繁琐，需要按照 jsdoc 规则来。

2.个人认为，jsdoc 有***性，文档规则需要写在代码中。

如果要写注释说明手册，对于大型项目，我推荐使用 apidoc ， 因为 apidoc ***性不强，不要求把规则写在代码中，可以把所有规则写到一个文件中。

但是一般小项目，没有必要单独写一份 api 文档。如果是开源的大型项目，首先需要考虑是否有开源的官方网站，你会看到网上的一些开源项目官网好像很酷，其实这个世界上不缺的就是轮子，你也可以很快的做出这样的网站，

下面我们来看看是如何做到的。

首先看一下 taro 源码，如下图：

这里就是生成一个静态网站的秘密，执行 npm run docs 就可以。用的是 docusaurus 包。

从上图中可以知道，文档的内容，来源于 docs 目录，里面都是 md 文件，开源项目的文档说明都在这里。

当然也有把对应的文档直接放到对应的代码目录下的，比如 ant-design 如下图：

就是直接把文档放在组件目录下了。

从这里我们可以知道，目前流行的开源项目的官方网站是怎么实现的，以及文档该怎么写。

三、我个人的注释习惯

下面说说我本人对函数注释(只针对函数注释)的一些个人风格或者意见。

1、分享 VSCode 关于注释的几个工具

• Better Comments 给注释上色

• Document This 自动生成注释

• TODO Highlight 高亮 TODO ，并可以搜寻所有 TODO

下面是一张演示图：

2、写和不写注释的平衡

我的观点是不影响可读性，复杂度低，对外界没有过度干涉的函数可以不写注释。

3、表达式语句的注释

函数内，表达式语句的注释可以简单点。如下图所示，// 后面加简要说明。

function add(a, b) {
// sum ....
let sum = a + b
}

4、TODO 注释

function say() {
// TODO: 编写 say 具体内容
console.log('say')
}

5、FIXME 注释

function fix() {
// FIXME: 删除 console.log方法
console.log('fix')
}

6、函数注释

一般分为普通函数和构造函数。

（1）普通函数注释：

/**
* add
* @param {Number} a - 数字
* @param {Number} b - 数字
* @returns {Number} result - 两个整数之和
*/
function add(a, b) {
// FIXME: 这里要对 a, b 参数进行类型判断
let result = a + b
return (result)
}

（2）构造函数注释：

class Kun {
/**
* @constructor
* @param {Object} opt - 配置对象 
*/
constructor(opt = {}) {
// 语句注释
this.config = opt
}
}

7、总结

从开源项目的代码中可以发现，在遵守注释的基本原则的基础上，注释的风格多种多样；同一个作者不同项目的注释风格也有所差别，但我会尽可能的去平衡注释和不注释。

（三）函数的鲁棒性(防御性编程)

下图是一个段子：

最后一句，测试测了那么多场景，最后酒吧还是炸了，怎么回事？

从中我们可以看出，防御性编程的核心是：

把所有可能会出现的异常都考虑到，并且做相应处理。

而我个人认为，防御性的程度要看其重要的程度。一般来说，不可能去处理所有情况的，但是提高代码鲁棒性的有效途径就是进行防御性的编程。

一、一个项目的思考

我曾经接手过一个需求，重写微信小程序的登录注册绑定功能，并将代码同步到其他小程序(和其他小程序的开发进行代码交接并协助 coder 平稳完成版本过渡)。

这个项目由于用户的基数很大，风险程度很高，需要考虑很多场景，比如：

1. 是否支持线上版本回退，也就是需要有前端的 AB 版本方案(线上有任何问题，可以快速切到旧登录方案)

2. 需要有各种验证：图形验证码、短信验证码、ip 、人机、设备指纹、风控、各种异常处理、异常埋点上报等。

3. 代码层面的考虑：通过代码优化，缩短总的响应时间，提高用户体验。

4. 如何确保单个节点出问题，不会影响整个登录流程。

如何去合理的完成这个需求还是比较有难度的。

PS: 关于第4点的如何确保单个节点出问题，不会影响整个登录流程，文末有答案。

下面我就关于函数鲁棒性，说一说我个人的一些看法。

二、前端函数鲁棒性的几种方式

1、入参要鲁棒性

在 ES6+ 到来后，函数的入参写法已经得到了质的提高和优化。看下面代码：

function print(obj = {}) {
console.log('name', obj.name)
console.log('age', obj.age)
}

print 函数，入参是 obj 通过 obj = {} 来给入参设置默认的参数值，从而提高入参的鲁棒性。

同时会发现，如果入参的默认值是 {} ，那函数里面的 obj.name 就会是 undefined ，这也不够鲁棒，所以下面就要说说函数内表达式语句的鲁棒性了。

2、函数内表达式语句要鲁棒性

继续上个例子：

function print(obj = {}) {
console.log('name:', obj.name || '未知姓名')
console.log('age:', obj.age || '未知年龄')
}

如果这样的话，表达式语句变得比较鲁棒性了，但还不够抽象，我们换种方式稍微把表达式语句给解耦一下，代码如下：

function print(obj = {}) {
const { name = '未知姓名', age = '未知年龄' } = obj
console.log('name:', name
console.log('age:', age)
}

上述代码其实还可以再抽象，比如把 console.log 封装成 log 函数，通过调用 log(name) ，就能完成 console.log('name:', name) 的功能。

3、函数异常处理的两个层面

• 防患于未然，从一开始就不要让异常发生。

• 异常如果出现了，该怎么去处理出现的异常。

那如何去更好的处理各种异常，提高函数的鲁棒性呢，我个人有以下几点看法。

4、推导一下 try/catch 的原理

js 在 node.js 提供的运行时环境中运行，node.js 是用 C++ 写的。C++ 有自己的异常处理机制，也是有 try/catch 。即 js 的 try/catch 的底层实现是直接通过桥，调用 C++ 的 try/catch 。

而 C++ 的 try/catch 具有一些特性，如try/catch 只能捕捉当前线程的异常。这样就解释了为什么 JS 的 try/catch 只能捕捉到同步的异常，而对于异步的异常就无能为力了(因为异步是放在另一个线程中执行的)。

这里是我的推导，不代表确切答案。

这里我推荐一篇博客：《C++中try、catch 异常处理机制》 ，有兴趣的可以看看。

5、合理的处理异常

第一个方法：如果是同步操作，可以用 throw 来传递异常

看下面代码：

try {
throw new Error('hello godkun, i am an Error ')
console.log('throw 之后的处代码不执行')
} catch (e) {
console.log(e.message)
}

首先 throw 是以同步的方式传递异常的，也就是 throw 要和使用 throw 传递错误的函数拥有相同的上下文环境。

如果上下文环境中，都没有使用 try/catch 的话，但是又 throw 了异常，那么程序大概率会崩溃。

如果是 nodejs ，此时应该再加一个进程级的 uncaughtException 来捕捉这种没有被捕捉的异常。通常还会加上 unhandledRejection 的异常处理。

第二个方法：如果是异步的操作

有三种方式：

1. 使用 callback ，比如 nodejs 的 error first 风格。

2. 对于复杂的情况可以使用基于 Event 的方式来做，调用者来监听对象的 error 事件。

3. 使用 promise 和 async/await 来捕捉异常。

怎么去选择哪个方式呢？依据以下原则：

1. 简单的场景，直接使用 promise 和 async/await来捕捉异常。

2. 复杂的场景，比如可能会产生多个错误，这个时候最好用 Event 的方式。

第三个方法：如果既有异步操作又有同步操作

最好的方式就是使用最新的语法：async/await 来结合 promise 和 try/catch 来完成对既有同步操作又有异步操作的异常捕捉。

第四个方法：处理异常的一些抽象和封装

对处理异常的函数进行抽象和封装也是提高函数质量的一个途径。如何对处理异常进行抽象和封装呢？有几个方式可以搞定它：

1. 第一种方式：对 nodejs 来说，通常将异常处理封装成中间件，比如基于 express/koa 的异常中间件，通常情况下，处理异常的中间件要作为最后一个中间件加载，目的是为了捕获之前的所有中间件可能出现的错误。

2. 第二种方式：对前端或者 nodejs 来说，可以将异常处理封装成模块，类似 Event 的那种。

3. 第三种方式：使用装饰器模式，对函数装饰异常处理模块，比如通过装饰器对当前函数包裹一层 try/catch 。

4. 第四种方式：使用函数式编程中的函子( Monad )等来对异常处理进行统一包裹，这里 的 Monad 和 try/catch 在表现上都相当于一个容器，这是一个相当强大的方法。从 Monad 可以扩展出很多异常处理的黑科技，但是我建议慎用，因为不是所有人都能看懂的，要考虑团队的整体技术能力，当然一个人的话，那就随便嗨了。

合理的处理异常，根据具体情况来确定使用合理的方式处理异常

It is recommended that a blog: "Evolution Callback Promise Generator Async-Await and exception handling."

Third, how to ensure that a single node problems, will not affect the entire login process

For example, the login process requires four security verification, according to the usual wording, one hung up, hang it all, but this is not enough robustness, how to solve this problem.

The main program will use the promise of a chain wording for a way to write, the previous wording is as follows:

Pseudo-code as follows:

auth().then(getIP).then(getToken).then(autoLogin).then(xxx).catch(function(){})

After a robust adjustment, it can be changed to the following wording:

Pseudo-code as follows:

auth().catch(goAuthErrorHandle).then(getIP).catch(goIPErrorHandle).then(function(r){})

After fine-tuning code, log in directly to the robustness of the process improved a lot, even if the error after error handling can also continue to pass on to the next method.

Fourth, my personal views on exception handling

I personally think that for exception handling, or according to the actual situation analysis. About the following views:

To consider the maintainability of the project, team technical level

I had a demand, the use of a more abstract approach to anomalies such as functor, etc., although a handful of show (seek death), resulting in demand subsequent changes to this, I had to come.

To estimate the complexity and importance of good projects in advance.

For example, when doing a more important business, initially I did not think so needs exception handling details, and generally the first edition, when demand did not involve a lot of exception handling, but the subsequent demand for an iterative optimization, I found exception handling It is so much a direct result of the need to rewrite code related to exception handling.

So later when the project evaluation, try to learn the importance of the project according to the pit in advance to reserve a good bit.

It would be a face of the future of programming mode.

V. Summary

Robustness of a function of (defensive programming), the paper describes a conventional method nodejs or distal handle exceptions.

Exception handling is not an easy living, you had to work in conjunction with business to determine the appropriate exception handling, in short, a lot of practice makes perfect.