前言
团队缺人，面试了不少同学，面试题都是类似的问题，例如有关框架的源码，webpack的原理等，然而在日常开发中基本是基于库的使用，随着前端技术的不断进步，这些api技术非常有可能会被淘汰。
js本就是自由灵活的，随着市面上层出不穷的框架为我们抽象封装了越来越多的东西以后，高速迭代的需求背后一个以业务为主的年轻程序员是否真的知道怎么在复杂场景下写出好代码？
纵观前端发展史上有名的框架&库源码(jquery-> angualr/react/vue)，总是被人拿出来反复研究，个人拙见，与其将面试题倒背如流(内卷)不如研究一下它们优良的编程细节和代码可读性。
❝技术原理是踏入公司的敲门砖，编程能力才是职业生涯的烙印，通用能力一定大于专业技术
❞
编程能力
总结为以下几点：
- 可读性
- 扩展性
- 可维护性
- 风险预知能力
可读性
❝可读性好的代码即便丢给一个实习生他也能快速看懂上手。
❞
工作已经辣么饱和了，是游戏不好玩还是电视不好看，请不要为难同行
归纳为以下几点：
- 见名知意、命名规范
- 代码逻辑容易理解
- 注释说明充分
现状
可读性随着开发人数的增多会变得越来越重要，而提升可读性的难度也会越来越大。
代码可读性好的团队不仅可以提效、节约交接成本，更可以让团队在公司中脱颖而出。
如果你是一个管理者想提升代码可读性，落地起来一定饱受争议，寸步难行。
大部分同学都会使用Eslint，或者TypeScript。
Eslint
ESLint 通过 AST 来分析代码，结合vscode的Eslint插件，在开发中就能做到即写即改，如果遇到想要的自定义配置需要自己提供eslintrc文件，常用的风格一般是airbnb。
- 需要制定代码规范且要求会非常严格，部分强迫症患者直接被逼死
- 踩坑，部分代码还需要额外的注释才能绕过检查解决冲突
- 已有项目造成的冲突不好改造（每个人的配置或编译器规则的不同、，项目直接跑不起来）
- 只能做到基础约束
TypeScript
从js的动态类型转为静态类型，增加了类型定义在严谨和安全性上有很好的约束，vscode有完美的提示支持，需要深入写好ts不容易，同时需要编译。
- 如果团队不熟悉那么学习成本还是有一些的
- 开发效率会有明显的减缓（排除AnyScript选手）
- 旧项目不好迁移、改造
Review
代码同行审查或上级审查
- 人力成本高
- 容易造成不积极的情绪
- 随着业务变多容易越来越难坚持下去
前面讲了一些提升代码可读性的方法，冷静下来思考这不是一件容易的事情，这些方案并不一定最符合当前的团队现状，任何一个都容易引起争议，但是这次真的有银弹，那就是写好「注释」。
这个时候我觉得大部分同学已经读不下去了，心里会想：就这？
答应我，要走的话拉到底并点完赞再走，可以吗~~o(╥﹏╥)o
why 注释
- 易于管理，心智负担低
- 提效，注释先行于方法，做一个快速预览
考虑到注释的可控性以及团队的执行力
坏注释
1.含糊、误导的注释
//计算函数
function toUpperCase(){}
//获取内容
function addToResult(){}
——————————— 分割线 ——————————————
//标题大写转换
function titleToUpperCase(){}
//相加后的结果
function addToResult(){}
2.过度、无意义的注释
//这是一段关于相加的函数，数字1+数字2产生了结果
function add (num1,num2){
return num1+num1;
}
//这个变量默认值为1
const num1 = 10;
ps: bro, 除非你在冲刺代码行数kpi否则你真的没必要这样
3.不统一规范的注释
//boy:description
const Boy = xxx
const Girl = zzz /* description for Girl */
4.甩锅注释
//后端说实现不了，数据格式就是那么坑
//项目经理说这里要慢一点，好让用户充钱优化
//抽奖写死中奖信息
//当你看到这行代码的时候我已经离职了，没有年终奖，好自为之
......
ps: 有些事情不说比较好。。。
好注释
先来康康不同场景注释需要的内容
- sdk、class、utils函数等公共内容
- 可能被误认为错误的代码、Hack写法等（这些应该尽量少出现）
- 复杂的、包含业务逻辑的判断条件（各种数字类型）
- VO数据转换
- 预留或没有解决突发状况的特殊内容需要注意
个人总结出标准注释中需要包含的内容（采用jsDoc的命名）
函数
description 描述
param 入参内容
return 返回内容
复杂对象声明（Object）
description
property 内部的属性名
公共变量、对象
type 通用抽象名
枚举、工具函数、sdk、npm包
author 作者（快速定位作者提出需求）
无论使用何种方式，标准的团队注释都需要规范化这些必填内容。
jsdoc
函数
/**
* @description 日期包含时间格式化
* @param {Date} [time] 函数 需要格式化的时间戳 可选
* @param {Boolean} needTime 是否包含当前时间
* @return {Stirng} dateTime 结果
*/
function timeFormat(time='', needTime) {
const date = new Date(time);
const year = date.getFullYear();
const month = ((date.getMonth() + 1) + 100).toString().substr(1);
const day = (date.getDate() + 100).toString().substr(1);
const dateTime = `${year}-${month}-${day}`;
if (needTime) {
return `${dateTime} ${date.toTimeString().substr(0, 8)}`;
}
return dateTime;
}
———————————————————————————————————————————————————————————————————
定义复杂类型
/**
*
* @description 用户信息-全局通用
* @typedef {Object} userInfo
* @property {String} name 姓名
* @property {Number} age 年龄
* @property {Number} [sex] 性别 可选参数
*/
使用
/**
* @type {userInfo} userInfo
*/
var userInfo = {
name: 'json',
age: 18,
sex: 'maile'
}
或
/**
* @param {userInfo} userInfo
*/
function setUserInfo (userInfo) {}
「在js文件顶部引入注释@ts-check会给出ts检查的提示」
//@ts-check
缺点
- 数据类型复杂的情况下不是那么好用，泛型不好用
.d.ts
这里考虑的是已有的js项目使用.d.ts
写过ts的同学应该都很熟悉，官网也能看语法不做过多描述
定义全局type类型
declare interface userInfo {
name: string,
age: number,
sex?: string
}
缺点
- 非ts项目书写同名ts文件导致项目内部文件解构混乱（跨文件夹引用type）
- 非ts项目且非vscode开发环境下（webstorm），提示作用不明显
利益权衡之后，有 「历史包袱」 的前提下建议选择使用jsdoc，新项目推荐ts
落地
「接口数据转换层」
在开发的时候帮助其他同学快速理解业务，约定入参和返回数据格式。
Tips：这里return和params的如果不会复用（90%），可以尝试一次性的写法
/**
* @description 获取用户信息列表并转换
* 接口文档地址： http://yapi.guahao.cn/project/xxxx
* 入参
* @param {Object} params 请求参数
* @param {String} params.name 姓名
* @param {Number} params.age 年龄
* 返回
* @typedef {Object} result
* @property {Array<Object>} data
* @property {Number} total
*
* @return {result} result 返回内容
*/
async getXxxList(params) {
const res = await $fetch('/api/xxx/list', params)
const { results, totalCount } = res.data.data;
return { data: results, total: totalCount };
}
「sdk、npm包、工具函数、类、通用枚举、变量」
公共内容加 注释 === 专业 === 架构师 ，你学会了吗？
Tips
vscode 有快速生成jsdoc的插件
看完别忘记对我素质四连，点赞、关注、转发、评论
加入我们，请认准保安唯一 邮箱: 「yangyz1@wedoctor.com」 weixin:「yyzv587」
