余晖落尽暮晚霞,黄昏迟暮远山寻
本站
当前位置:网站首页 > 编程知识 > 正文

JavaScript 编码规范案例(javascript编程规范)

xiyangw 2022-11-25 11:27 83 浏览 0 评论

前端代码编码和设计规范系列——JavaScript编程规范

置顶 浪里沙 2016-07-15 15:43:19 3905 收藏 7

分类专栏: 规范文档 文章标签: javascript 设计规范 前端 文档

版权

规范文档

专栏收录该内容

0 篇文章0 订阅

订阅专栏

1文档信息

条目

内容

项目编号

通用

项目名称

通用

标题

JavaScript编程规范

类别

规范文档

当前

试用草稿

摘要


当前版本

V1.0

日期

2015/11/9

作者

徐维坚(xuweijian)

文档拥有者

内部公开

文件

前端规范系列-JavaScript篇.docx

2修改历史

编号

修订人

修订内容简述

修订

日期

修订前

版本号

修订后

版本号

V0001

徐维坚

编程规范文件编写,草稿试用版公布

2015/11/10


V1.0







规范前言

良好的编程规范对于软件的开发与维护,至关重要!他不仅可以提高代码的可读性、可靠性、有效性、健壮性,而且利于帮助开发人员开发和维护代码。对于一个团队协作的项目来说,人员的变动,一个良好的编程规范,有助于后续开发者和新手快速了解项目代码所要表现的含义。

1 范围

本规范规定了使用JavaScript语言编程时排版、命名、声明、作用域、及一些特殊符号的规则和建议。

本规范适用于使用JavaScript语言编程的产品和项目。

2 术语和定义

规则:编程时强制必须遵守的原则。

建议:编程时必须加以考虑的原则。

格式:对此规范格式的的说明。

说明:对此规范或建议进行必要的解释。

实例/如:对此规范或建议从正、反两个方面给出的例子。

1命名规范

1.1基本规则

规范的命名能使程序更易阅读,从而更易于理解。它们也可以提供一些标识功能方面的信息,有助于更好的理解代码和应用。

1) 规则一:使用可以准确说明变量、函数、原型(prototype)的完整英文描述符。严禁使用汉语拼音、不相关单词及汉字进行命名,实例:firstName,listAllUsers或 CorporateCustomer等;

2) 规则二:尽量少用缩写,但如果一定要使用或名称过长(不超过 25 个字母),当使用公共缩写和习惯缩写等,如实现(implement)可缩写成impl,经理(manager)可缩写成mgr等,严禁滥用缩写;

3) 规则三:变量命名必须以小写字母开头,命名使用骆峰命名规则;

4) 规则四:方法名必须使用动词或动词短语命名,实例:getIdcName()、export()等;

5) 规则五:避免使用相似或者仅在大小写上有区别的名字,以免不严格区分大小写的系统视为同一名称;

6) 规则六:避免命名中含有数字,但可以用2表示to,4表示for,另末尾使用数字表示同一系列的除外,如var$td_1 = $(‘.grid td’)[1];

7) 规则七:类名、构造函数、公共对象实例等名称首字母大写。

var MyCommon = {undefined

getSmallClassFromBigClass: function() {}

}


1.2相关建议

以下为相关建议,非必要遵循,但需要考虑

1) 建议一:变量如果设置为私有变量,函数为私有函数,则前面添加下划线进行标注;公有变量和函数不添加下划线

实例一:

var MyClass = function() {undefined

var _thisTotal = 0;

var _doSomething = function() {};

this.getThisTotal = function() {undefined

return _thisTotal;

};

};

var myClassInstance = new MyClass();

myClassInstance.total = myClassInstance. getThisTotal();

实例二:

function MyClass() {undefined

this._thisTotal = 0;

this._doSomething = function() {};

}

MyClass.prototype.getThisTotal = function() {undefined

return this._thisTotal;

};

var myClassInstance = new MyClass();

myClassInstance.total = myClassInstance.getThisTotal();

2) 建议二:前面加"is" 的变量名应该为布尔值,同理 "has","can" 或者 "should"亦如此;

3) 建议三:重复变量建议使用"i", "j", "k" (依次类推)等名称的变量;

4) 建议四:全局变量、常量应该全部大写;

5) 建议五:术语"initialize" 或者 "init" 作为变量名应为已经实例化(初始化)完成的类或者其他类型的变量;为函数,应为初始化操作。

2代码组织规范

基本原则:利于个人开发,便于相互交流。

【说明】:因个人习惯和编辑器等可以设置而形成自己独特的风格,但必须前后一致,并符合本规范的基本规则、建议和格式。

2.1缩排

原则:

(1)代码中以TAB(4个字符)缩进,在编辑器中请将TAB设置为相同的长度,否则在不同编辑器或设置下会导致TAB长度不等而影响整个程序代码的格式;

(2)同一代码块中的代码对齐,这里所说的代码块,包括但不限于:function、if else语句、while、for等,即使用{}包围的代码。

2.1注释

原则:不吝惜代码注释,重要函数、变量必须添加注释;特殊函数、变量、常量必须添加注释。

注释的格式,可参考如下所示:

1)变量注释:

// 初始化序列号

var index = 0;

var index = 0; // 初始化序列号


2)函数注释,包括a.函数描述及其功能说明;b.参数描述应包括类型、参数名、参数描述;有返回值的需要对返回值进行相应描述:

/**

* 绑定事件

* @param {Object} $detailDom 当前变更详情页面主体DOM对象

* @return null

*/

function _bindEvent($detailDom) {undefined


/**

* 查看专线详情

* @param {jQueryObject} $grid 列表DOM容器

* @param {String} selector 需要添加详情链接的选择器

* @param {Boolean} needSpecialId 是否需要指定其他特定id,默认不传,即false

* @param {String} specialIdName needSpecialId为true,此值必传,即指定id的属性名称

* @return {Boolean} result 操作是否成功

*/

viewDetail: function($grid, selector, needSpecialId, specialIdName) {undefined

var self = this;



3)文件注释,应该包含文件描述、功能简介和作者,还可以加上创建时间:

/**

* 本js实现专线续费申请页面所有功能

* @author xuweijian

* @date 2015/10/12 15:25:33

*/

$(function() {undefined


4)行注释与块注释:使用 //…的注释方法来注释需要表明的内容;使用/**和*/注释的方法来注释需要表明的内容。

3 编码规范

3.1 变量编码规范

原则:在遵循命名规则之上,应遵守以下规则,

(1)申明多个变量,变量之间使用逗号分隔;同时建议逗号与变量之间添加一个空格,避免过于拥挤,或是换行申明(此时可以对某个变量添加注释!),

实例一:

var name = ‘’, value = ‘’, title = ‘’;

实例二:

var name = ‘’,

value = ‘’, // 注释

title = ‘’;


(2)变量申明时,应明确变量的类型,可以立即赋值,尽量避免变量的类型在使用过程中被转换;

(3)尽量避免魔数(Magicnumbers),他们应该使用常量来代替;

(4)声明变量必须加上 var 关键字,否则将成为全局变量(Document或者 Window),进而成为污染全局的变量;

3.2 函数编码规范

原则:

(1) 所有的函数在使用前进行声明,内函数的声明跟在var 语句的后面;

(2) 不要在语句块(if…else等)内声明一个函数;


其编码风格应该遵循这几点建议:

1) 建议一:函数名与参数()之间不要留有空格;

2) 建议二:参数列表之间使用逗号分隔,逗号与参数之间留有一个空格;

3) 建议三:使用右侧简约模式,)与{之间留一个空格;

4) 建议四:避免参数过多现象,一般不超5个,过多使用对象传入;

5) 建议五:匿名函数不应该换行,如:$(‘#id’).bind(function(){…});中参数为匿名函数不应该换行处理,函数的主体遵循前面建议与原则;


function outer(c,d)

{undefined

var e = c * d;

function inner(a, b)

{undefined

return (e * a) + b;

}

return inner(0, 1);

}

// 简约模式

function outer(c,d) {undefined

var e = c * d;

function inner(a, b) {undefined

return (e * a) + b;

}

return inner(0, 1);

}



在函数体中,我们应遵循以下建议:

1)建议一:避免提供多个出口;

//不要使用这种方式,当处理程序段很长时将很难找到出口点

if (condition) {undefined

return A;

} else {undefined

return B;

}


//建议使用如下方式

var result = null;

if (condition) {undefined

result = A;

} else {undefined

result = B;

}

return result;


2)建议二:函数体中代码不应过长,一般不要超过100行;

3.3表达式与语句

原则:表达式和语句应清晰、简洁,易于阅读和理解,避免使用晦涩难懂的语句。使用圆括号明确表达式执行优先级。

3.3.1控制语句

1)建议一:判断中如有常量,则应将常量置与判断式的右侧。如:

if ( true == isAdmin())...

if ( null == user)...

2)建议二:boolean类型判断语句尽量明确条件比较值true/false

//不建议使用

if (isCond)...

if (!isCond)...


//尽量使用

if (true == isCond)…

if (false == isCond)…

if (true != isCond)…


编码风格应遵循以下建议:

(1) 建议一:if…else if…else语句必须使用{}将每个判断条件后的执行语句括起来。

(2) 建议二:if…else if…else与小括号、大括号之间应该空一格;

(3) 建议三:条件中的变量与“==”、“===”之间应该空一格;

(4) 建议四:类型确定的变量,在比较时,应使用严格相等符“===”,即”0” ===0比较值是false。

3.3.2循环语句

原则:

(1) 循环中必须有终止循环的条件或语句,避免死循环。

(2) 当多层循环嵌套时,计数器变量注意不要有冲突。

(3) 注意循环条件在执行循环过程中是否会发生变化,如果会则必须把循环条件的值在执行循环前获取而不要在每次循环去执行。

(4) 考虑运行效率问题也应把循环条件值放在循环执行前获取。


建议:

(1) 使用最基本的for循环,尽量避免使用for …in循环;

(2) for …in循环可用于用于object/map/hash 的遍历,对 Array 用 for-in 循环有时会出错,不建议使用;

(3) for循环中条件语句,不应该每次执行一个操作(如计算),应该在初始语句中实现;

// 不建议每次查询length的值

for (var i = 0; i < data.length; i++) {undefined


}

// 建议在初始语句中赋值一个变量

for (var i = 0, len = data.length; i < len; i++) {undefined


}

3.3.3语句规范

原则:

(1) 除了语句块最后一条语句可以没有分号“;”以外,每条语句必须以分号结束,以避免代码压缩后造成解析失败。

(2) 当代码块中只有一条语句,也不应该省略大括号,如

if (null == $tab) {undefined

return ; // 虽然只有一条语句,也不应该省略{}

}


3.3.4运算符规范

原则:

(1) 赋值符号、比较符号两侧的变量应该在同一行,不要进行换行;

(2) 字符串使用单引号(’)要优于双引号(”),尤其是在创建一个包含 HTML 代码的字符串时;

3.4类、对象与原型链规范

原则:

(1) 使用 Array 和 Object 字面量语法, 而不使用 Array 和 Object 构造器(newArray()),避免因传参不合适导致错误;

(2) 其命名规范参考第1节中命名规范;


编码风格,建议如下:

1)比较长的标识符或者数值, 不要为了让代码好看些而手工对齐. 如:

CORRECT_Object.prototype = {undefined

a: 0,

b: 1,

lengthyName: 2

};

不要这样做:

WRONG_Object.prototype = {undefined

a : 0,

b : 1,

lengthyName: 2

};


2)属性名与属性值之间不应该拥挤,应该在冒号“:”与属性值之间空一格;


3.5错误处理

基本原则:

(1) 通常的法则是系统在正常状态并且用户正常操作下,不应产生任何异常。

(2) 对可预见的错误不进行捕捉。

(3) 对不可预见或者难以解决错误进行try{…}catch(e){..}捕捉处理。

3.5.1可预见错误

对可预见的错误不进行捕捉处理,而是在错误发生前通过条件判断避免发生,如:

//若不对div1是否为null进行检查,则在其为null时会抛出缺少对象错误

document.getElementById(“div1”).style.width = 100;



//预先对对象进行检查

var objDiv1 = document.getElementById(“div1”);

if(objDiv1!=null){undefined

objDiv1.style.width = 100;

}

3.5.2不可预见错误

对不可预见或者因浏览器、脚本解析器BUG造成的难以解决的错误需要进行捕捉处理,如:

try{undefined

xmlhttp.open(“GET”,url,NOT_ASYNC);

}catch(e){undefined

console.log(e.description);

}


【说明】:对捕捉到的错误一般情况必须给出反馈处理,例如console.log(),除非有必要提醒用户,否则不应该使用alert()。

4 JavaScript其他规范

以下规范,除了说明为建议、格式外,均为必须遵循的原则:

(1) eval是恶魔。eval 是JavaScript中最容易被滥用的方法,避免使用它。

(2) 不要给setTimeout或者setInterval 传递字符串参数,应该使用函数参数。

(3) this仅在对象构造器, 方法, 闭包中使用。

this 的语义很特别。 有时它引用一个全局对象(大多数情况下),调用者的作用域,DOM 树中的节点(添加事件处理函数时), 新创建的对象(使用一个构造器),或者其他对象(如果函数被call()或apply())。使用时很容易出错。

【说明】:在内嵌函数想要使用外层函数的调用者,必须将外层调用者赋值给一个变量,通常是self。

(4) 不要使用with(){}。

(5) 千万不要修改内置对象, 如Object.prototype 和 Array.prototype 的原型;

(6) 使用 join() 来创建字符串。

通常是这样使用的,但这样在 IE 下非常慢:

function listHtml(items) {undefined

var html = '<div class="foo">';

for (var i = 0, len = items.length; i < len; ++i) {undefined

if (i > 0) {undefined

html += ', ';

}

html += itemHtml(items[i]);

}

html += '</div>';

return html;

}

可以用下面的方式:

function listHtml(items) {undefined

var html = [];

for (var i = 0, len = items.length; i < len; ++i) {undefined

html[i] = itemHtml(items[i]);

}

return '<div class="foo">' + html.join(', ') + '</div>';

}



【说明】:即用数组作为字符串构造器, 然后通过join('') 转换成字符串。不过由于赋值操作快于数组的 push(), 所以尽量使用赋值操作.














【参考文献】

[1] JavaScript编程规范. http://wenku.baidu.com/view/f3a4cde95ef7ba0d4a733b38.html

[2] Google JavaScript 编码规范指南. http://wenku.baidu.com/view/3a045b66b84ae45c3b358c18.html?re=view

[3] js编码规范. http://wenku.baidu.com/view/ccd97ba20029bd64783e2c0e.html

[4] javascript编程规范. http://wenku.baidu.com/view/b6e6a7d376eeaeaad1f3301e.html

相关推荐

高效删除文件名中的指定内容,祛除烦恼

如何快速批量删除文件名中的指定字符?在电脑整理文件时,我们常常需要进行批量重命名操作。如果文件名中含有不必要或重复的字符,这将影响文件的识别和查找。因此,删除这些文字或字符是非常必要且有效的。本文将分...

你的手机是不是经常提示存储空间不足?Python帮你清理重复文件

  最近我的手机经常提示存储空间不足,主要是微信和QQ群里接收的文件太多了,平时也没怎么整理。我把这些文件从手机里拷出来,打算整理一下,把该删的文件都删掉,把要备份的文件分门别类存到电脑或网盘上。我突...

从零开始打造云端AI管理调度平台(四)如何设计主页_1

最近闲来无事,想着把自己工作正在做的一个项目做一个简单的分享与实战教程,该项目不困难但是由于涉及要素过多所以比较复杂。所以这里分享出来也是为了帮助新手小白能在实战当中快速了解python知识。主要内容...

「万能Python」-17-标准库OS_python2.7标准库

Python的库是指预先编写好的代码集合,可以用来处理特定的任务或实现特定的功能。Python的标准库提供了许多常用的标准库,无需安装引入使用。Python3的标准库提供了许多常用的功能,包括...

十多行代码生成原帖和临写对照图_几十行代码可以申请软著吗

介绍这个小工具把原帖和临写分解成多列对照的形式。输入原帖图片,和输入临写图片,生成对照图片。使用说明运行compare.py文件,输入参数为:原帖图片文件名,临写图片文件名,列数。python3co...

Python合集之目录操作(四)_python之文件操作大全

1.删除目录删除目录可以通过os模块提供的rmdir()函数实现。通过rmdir()函数删除目录时,只有当要删除的目录为空时才起作用。os.rmdir(path)path为要删除的目录,可以使用绝对路...

excel办公自动化,自动合并excel表格

平时时收到不同人反馈的excel表格,需要将其合并在一个excel中,每个excel打开复制粘贴会很慢,如下脚本可一键合并所有的exceldefauto_merge():try:print('...

批量打开一个文件夹下面所有的excel表格

如果现在有一个文件夹,名称叫做“练习表格”,路径名是'C:\Users\123\Desktop\练习表格',现在的要求是打开这个文件下面所有的excel表格,后缀名字为“xlsx”,我...

500行代码,教你用python写个微信飞机大战

这几天在重温微信小游戏的飞机大战,玩着玩着就在思考人生了,这飞机大战怎么就可以做的那么好,操作简单,简单上手。帮助蹲厕族、YP族、饭圈女孩在无聊之余可以有一样东西让他们振作起来!让他们的左手/右手...

python 日志写入_python日志文件写入

1.第一步,新建日志文件路径,如下图:2.日志模块封装,代码如下:importlogging,oslogs_path=os.path.join(os.path.dirname(__file...

Python os.path模块使用指南:轻松处理文件路径

前言在Python编程中,文件和目录的操作是非常重要的一部分。为了方便用户进行文件和目录的操作,Python标准库提供了os模块。其中,os.path子模块提供了一些处理文件路径的函数和方法。本文主要...

Python中获取当前路径之pathilb和os的区别

20230114星期六:1,直接在py脚本中,执行,没有区别;2,打包成exe文件以后,在本机执行,有区别,这时,不能使用os.path.dirname(__file__),只能使用pathlib.P...

Python(办公自动化编程系列)学习笔记1

1、获得当前程序工作目录importos#os.getcwd()函数可以取得当前工作路径的字符串print(os.getcwd())运行结果2、获得程序文件夹相对路径#相对路径都用/表示#../...

文件路径名Pathnames的操作_路径和文件名是什么意思

1.现象问题使用路径名来获取文件名,目录名,绝对路径等等2.原因分析无3.问题解决使用os.path模块中的函数来操作路径名importos.path#查看标准化的绝对路径print...

关于《Python入门:os常用函数》中复制文件(夹)函数从简到繁

基本考虑练习os模块及file读写操作:将给定的源路径的文件(夹)复制到目标路径简单实现#文件到文件的复制path_src='E:\src.txt'path_tar='D...

取消回复欢迎 发表评论: