前端代码规范

未来已来2018-09-10 13:42

 作者:罗宸


一. 概述

为了统一前端开发的代码风格,以便后续代码的管理和维护,在使用前端开发框架时请遵循本文档制定的规范编写代码。 本文档涉及的规范主要包含四个方面:注释规范、命名规范、“类”模型、控件规范,另外会简要的说明系统发布的情况。


二. 注释规范

良好的注释可以增加代码的可读性和可维护性

1. 文件注释

文件注释用来说明当前文件所实现内容,主要包括说明部分和作者部分。

说明部分:描述文件实现的功能、模块或接口等,如有需要增加使用说明或者范例。

作者部分:记录文件的开发者名称和联系方式,用以后续的维护或者交流沟通等。

依赖部分:记录当前文件直接依赖的其他文件,便于工具构建依赖关系。

注释范例如下图所示:

/**
* ------------------------------------------
* 水平滑动器逻辑封装实现文件
* @version 1.0
* @author genify(caijf@corp.netease.com)
* ------------------------------------------
*/

关于这部分,如果使用Eclipse做为开发工具的话可以将其做成一个模板,在新建JS文件时可自动生成。

2. 接口注释

接口注释用来描述当前定义的接口的功能及输入输出数据,主要包括说明部分、输入部分、输出部分。

说明部分:说明当前接口的功能,如有需要可增加使用说明或者范例。

输入部分:说明输入数据的类型及含义。

输出部分:说明输出数据的类型及含义。

注释范例如下图所示:

/**
* 控件重置
* @param {Object} _options 可选配置参数
* @return {Void}
*/
_proAbstract.__reset = function(_options){
this.__supReset(_options);
this.__doInitClass(_options.clazz);
this._$appendTo(_options.parent);
};

关于这部分,如果使用EclipseAptana插件,则在接口写好后直接输入“/**”然后回车会自动生成默认的注释。

3. “类”注释

“类”注释用来说明当前类的基本功能、继承关系及可接收初始输入数据,主要包括功能描述部分、继承关系部分、初始数据部分。关于这里的“类”可参阅JAVASCRIPT类模型部分的详细说明。

功能描述部分:描述类所代表的对象及基本功能,如需要可增加使用说明或范例。

继承关系部分:说明类的父类,以便于代码的回溯。

初始数据部分:类对象在实例化时可接收这些数据做为初始信息。

注释范例如下图所示:

/**
* 提示建议控件
* @class 提示建议控件
* @extends nej.ui._$$Abstract
* @param {Object} _options 可选配置参数,已处理参数列表如下
* input [Node|String] - 输入框节点或者ID
* onselect [Function] - 选中触发事件
* onchange [Function] - 输入内容变化触发事件
*/
_p._$$Suggest = NEJ.C();
_proSuggest = _p._$$Suggest._$extend(_p._$$Abstract);
_supSuggest = _p._$$Suggest._$supro;


三. 命名规范

本部分的规范主要为项目发布时的压缩混淆做准备

1. 命名空间

规则:小写字母

说明:系统的命名空间通过基础库中window.P接口增加,会以字符串的形式出现,在系统发布时不予混淆,因此选择命名空间时不易选用过于复杂的名称。

注:基础库的接口命名空间采用单个大写字母,独立项目中不宜使用此命名空间的名称规则 范例:op.tsk, lv.sys

var _  = NEJ.P,
_o = NEJ.O,

4. “类”接口的实现

根据“类”的需要实现其他接口,在子“类”的其他接口中如果需要调父“类”的同名接口采用以下方式 子类实现的接口是__init,__initNode,__destory,__reset的方法,要调用父类的方法可以用 __supInit, __supInitNode __supDestroy, __supReset 如初使化方法:

/**
* 控件重置
* @param {Object} _options 可选配置参数
* @return {Void}
*/
_proAbstract.__reset = function(_options){
this.__supReset(_options);
this.__doInitClass(_options.clazz);
this._$appendTo(_options.parent);
};

如果不是上面的4类接口,假设需要调用setData的父类方法就需要如此写了

/**
* 加载中控件
* @class 加载中控件
* @param {Object} _options 可选配置参数,已处理参数列表如下:

定义数组和对象,要用字面量:

var _a = {};

var _b =[];

7 换行

if的判断语句超长时,要在适合的地方换行:

if(_list[i].fid!=__subFolderId&&

_list[i].fid!=__advFolderId&&

_list[i].fid!=__garbageFolderId&&

_list[i].fid!=__draftFolderId&&

_list[i].fid!=__deletedFolderId){

_usedList.push(_list[i]);//_list.splice(i,1);

}

函数参数,如果一个函数的参数很多,需要对参数进行对齐:

__proCacheDB._$deleteMessages = function(_username,_ckey,

_messageIds,_tofid,_crossPages){

8 匿名函数

函数体需要重起一个

_proEvent.__destroy = (function(){


var _doRemoveEvent = function(_args,_key,_map){

delete _map[_key];

_v._$delEvent.apply(_v,_args);

};
return function(){

this._$clearEvent();

_u._$forIn(this.__events_dom,_doRemoveEvent);

};

})();

9 三元操作符

三元操作符的格式,以下三种应该都是可行的

var _x = _a ? _b : _c;
var _y = a ?
_loginButSimpleOperandB : _longButSimpleOperandC;
var _a = _a ?
_loginButSimpleOperandB :
_longButSimpleOperandC;

10 事件命名

添加节点事件的命名规则 on + 名词 + 动作 符合驼峰规则 如页面上有一个editBtn的按钮,要给这个按钮添加点击事件时,可以命名成onEditBtnClick,如果是鼠标悬停,onEditBtnMouseover等这样的一种命名规则 除了事件的命名外,其他的所有回调函数都以cb开头,如item里对模块的回调,cache对外面的回调等都以__cb开头 + 名词 + 动词

11 Array遍历

统一写法:

for(var i = 0,l = _array.length; i<l; i++){
}

12 定义多个变量

var定义多个变量时,如果某个变量初始化了,就另起一行,重新用一个var来定义余下的变量

var _a, _b, _c = true;
var _i, _b = false;
var _e;



本文来自网易实践者社区,经作者罗宸权发布