JavaScript开发规范

Posted 2022-08-26 echolun

 壹 ? 引

当一个团队开发同一个项目时，无论使用的是什么技术，每个人开发习惯的不同，最终代码呈现总有差异；A同事不爱写注释，B同事命名上总是随心所欲，虽然功能都能实现，但对于几个月，或很久之后的维护造成了极大的阻碍，因此统一一个开发团队的编程规范很有必要。这份规范几个月前就整理好了，前端组目前的开发也以此为标准，其实对于我来说也是一种个人财富吧，所以这里还是整理为博客。

本文主要从命名、注释、编程规范与项目文件命名四个方面展开，公司要求不同最终规范肯定不会完全一致，但愿此规范能对你的提供一点思路与帮助，那么本文开始：

 贰 ? 命名(变量/常量/函数)

1.变量

变量命名推荐采用小驼峰命名法---即首字母小写，后每个单词首字母大写。

// good
let name = ‘听风是风‘;
let userName = ‘echo‘;
// bad
let username = ‘时间跳跃‘;

2.常量

常量命名推荐采用全字母大写命名，以便于与变量区分。

// good
const PI = 3.141592653;
// bad
const pi = 3.141592653;

3.函数

函数命名推荐使用小驼峰命名法，条件允许情况下请采用动词前缀方式，请保证函数命名语义化明确。

// 判断是否能执行某个操作/权限
function canLogin() ;
// 判断是否有某个值
function hasUserName() ;
// 判断是否是某个值
function isUserName() ;
// 获取某个值
function getUserName() ;
// 设置某个值
function setUserName() ;
// 加载数据
function loadData() ;
// ...

4.构造函数

构造函数命名必须采用大驼峰命名法，即首字母必须大写。

// good
function Student(name) 
    this.name = name;
;

 叁 ? 注释

1.单行注释

采用 // 方式注释：

// 这是我的博客名
let name = ‘听风是风‘;

2.多行注释

采用 /** */ 方式注释：

/**
 * 这是我的博客名
 * 听风是风，且听风吟
 */
let name = ‘听风是风‘;

3.函数注释

函数注释也是多行注释的一种，但要求提供函数功能说明，作者信息，参数说明(若有参数)，以及返回值(若有返回值)说明。

/**
 * @desc 用于计算两数之和
 * @author 听风是风
 * @param Number x 数字，用于加法计算
 * @param Number y 数字，用于加法计算
 * @return Number result 用于保存计算后的结果
 */
function add(x, y) 
    let result = x + y;
    return result;
;

 肆 ? 编程规范

1.推荐使用对象直接量创建对象，而非构造器创建

// 创建普通对象
// good
let obj = a: 1
// bad
let obj = new Object();
obj.a = 1;

// 创建数组
// good
let arr = [1,2,3];
// bad
let arr = new Array();
arr[0] = 1;
arr[1] = 2;
arr[2] = 3;

// 创建函数
// good
function getName(); //函数声明
let getName = function() ; //函数表达式
// bad
let getName = new Function();

2.字符串拼接推荐使用ES6中` `拼接

// good
let str = `hello, my name is $变量.`;
// bad
let str = "hello, my name is " + 变量 + " ."

3.比较运算符

永远推荐使用"==="与"!=="而非"=="与"!="，在允许的情况下，推荐使用比较运算符简写进行判断：

// good
if(a === 1);
if(a !== 1)

比较运算符简写的规则：

a.对象被认为是true

b.Undefined，Null，空字符串被计算为false

c.布尔值根据自身值判断为true或false

d.数字+0，-0或NaN被计算为false，否则为true

// good
if(name);
// bad
if(name !== ‘‘);
// good
if(arr.length);
// bad
if(arr.length > 0);
// good
if(!variable)
// bad
if(variable === false)

4.养成添加分号的习惯

let name = ‘听风是风‘;
const AGE = 26;

5.空格与代码缩进

请结合vscode插件，如Beautify进行一键格式化。

6.代码空行

a.函数代码块前后请空行（当函数方紧接函数注释时，函数与注释间不需要换行）

let name = ‘听风是风‘;

//这是一个函数
function setName(name)
    let userName = name;
;

// 调用函数
setName(name);

b.注释前请空行（当注释在代码块的第一行时，则无需空行；若在函数内注释可不空行，集中声明多个变量添加注释时也可不空行）

// 名字
let name = ‘听风是风‘;
// 年龄
let age = 26;

//这是一个函数
function setName(name)
    // 设置用户名
    let userName = name;
    // 返回用户名
    return userName;
;

// 调用函数
setName(name);

c.变量声明下方请空行（如有多个变量集中声明，只在最后一个变量下方空行，函数内可不空行）

7.变量、函数请保证先声明后使用，统一作用域的变量声明请集中管理

虽然ES6使用let已经不存在变量提升，避免了这个问题，但若仍使用了var声明请遵守这一点。

// good
var a = 1;
console.log(a)
// bad
console.log(a)
var a = 1;

// good
function demo() console.log(1);
demo();
// bad
demo();
function demo() console.log(1);

同一作用域的变量声明请集中在顶端。

// good
function demo() 
    var a = 1;
    var b = 2;
    var c = 3;
    console.log(a);
    console.log(b);
;
// bad
function demo() 
    var a = 1;
    console.log(a);
    var b = 2;
    var c = 3;
    console.log(b);
;

8.关于循环

a.若循环中需使用函数，请将函数定义在循环外部而非内部，这样可以避免函数的反复创建。

// good
let demo = function (i) 
        console.log(i)
    ,
    i = 0,
    arr = [1, 2, 3],
    len = arr.length;
for (; i < len; i++) 
    demo(i);
;
// bad
let arr = [1, 2, 3],
    i = 0,
    len = arr.length;
for (; i < len; i++) 
    let demo = function () 
        console.log(i);
    ;
    demo();
;

上述bad写法中准确来说有两点不合理，第一点是demo函数会反复创建比较浪费内存；

第二点是严格来说函数只能在全局作用域或函数作用域下声明，但浏览器环境默认支持了非此类环境的创建行为，且ES6为了兼容早期写法，仍然允许此类写法，但我们应该清楚这一点。

b.循环中的常量

循环过程中例如数组的length属性在不变的情况下，提出循环外声明要比在for循环中创建更好。

// good
let i = 0,
    arr = [1, 2, 3],
    len = arr.length;
for (; i < len; i++) 
    console.log(i);
;
// bad
let arr = [1, 2, 3];
for (let i = 0; i < arr.length; i++) 
    console.log(i);
;

c.若循环操作与循环顺序无关，使用逆序遍历效果更好

// good
let arr = [1, 2, 3],
    len = arr.length;
while (len--) 
    console.log(1);
;

 伍 ? 项目文件命名规范

由于我们使用了angularjs开发项目，总会涉及到组件，服务等特殊文件，这里除了常见的html，less文件外，还会统一特殊文件的命名习惯。

1.html文件命名推荐采用小驼峰命名法+.html：

index.html
myAccount.html

2.less文件推荐采用小驼峰命名法+.less：

index.less
myAccount.less

3.controller控制器推荐小驼峰命名法+Ctrl+.js：

indexCtrl.js
myAccountCtrl.js

4.service推荐采用小驼峰命名法+.service+.js：

index.service.js
myAccount.service.js

5.component推荐采用小驼峰命名法+.component+.js，依赖模板与样式如下：

// 组件JS
myAccount.component.js
// 组件样式
myAccount.component.less
// 组件模板
myAccount.template.html

6.directive指令推荐小驼峰命名法+.directive+.js，模板样式同component

// 组件JS
myAccount.directive.js
// 组件样式
myAccount.directive.less
// 组件模板
myAccount.template.html

7.控制器，服务，组件，指令注册命名，推荐采用小驼峰命名

angular.module(‘myApp‘,[])
    .controller(‘myAccountCtrl‘,function()
        // 控制器
    )
    .service(‘myAccountService‘,function()
        // 服务
    )
    .directive(‘myAccountDirective‘,function() 
        // 指令
    )
    .component(‘myAccountComponent‘,
        // 组件
    )
    .filter(‘myAccountFilter‘,function()
        // 过滤器
    );

这样统一命名的好处是，当我们看到一个服务叫myAccountService，那么马上可以知道创建这个服务的文件名叫myAccount.Service.js。

我们保证文件名与注册名的一致性，这样对于文件查找是非常便捷的。

希望这些规范能对你有所帮助，本文结束。