代码规范的宗旨是不管有多少人共同参与同一项目,一定要确保每一行代码都像是同一个人编写的
为什么要有规范?
降低新成员融入团队的成本, 同时也一定程度避免挖坑;
提高开发效率、团队协作效率, 降低沟通成本;
实现高度统一的代码风格,方便review, 另外一方面可以提高项目的可维护性;
规范是实现自动化的基础;
规范是一个团队知识沉淀的直接输出;
规范包括哪些内容?
如前面提到的,前端协作规范并不单单指‘编码规范’,这个规范涉及到前端开发活动的方方面面,例如代码库的管理、前后端协作、代码规范、兼容性规范;
不仅仅是前端团队内部需要协作,一个完整的软件生命周期内,我们需要和产品/设计、后端(或者原生客户端团队)、测试进行协作, 我们需要覆盖这些内容。
命名规范:
1.图片的命名规范
banner-* //放置在页面顶部的广告、装饰图案等长方形的图片 logo-* //标志性的图片 btn-*-* //在页面上位置不固定并且带有链接的小图片;命名规范:btn-功能名-大小/私有 pic-* //装饰用的照片 tit-* //不带链接表示标题的图片 icon-* //一系列图标图片
2.注释
当你写注释时一定要注意:不要写你的代码都干了些什么,而要写你的代码为什么要这么写,背后的考量是什么。当然也可以加入所思考问题或是解决方案的链接地址。
在文件开始时写块注释:
/** * 作用于哪些页面 * 注明代码业务/功能说明 * @authors Your Name ([email protected]) * @date 2016-05-16 * @version $Id$ */ // 单行注释添加一个空格 var offset = 0; // 此处注明变量注释 if(includeLabels) { // If the labels are included we need to have a minimum offset of 20 pixels // We need to set it explicitly because of the following bug: // http://somebrowservendor.com/issue-tracker/ISSUE-1 offset = 20; }
模块功能描述说明
/** * ------------------------------------------------------------------ * 模块描述说明 * ------------------------------------------------------------------ */
模块内的小函数方法归类:
/** * 小函数方法归类说明,这些零散的小函数方法放在一起 对应 一个业务方法逻辑 * ------------------------------------------------------------------ */
单个函数注释
/** * 函数功能简述 * * 具体描述一些细节 * * @param {string} address 地址 * @param {array} com 商品数组 * @param {string} pay_status 支付方式 * @returns void * * @date 2014-04-12 * @author QETHAN<[email protected]> */
css注释的写法:
/* Footer */ 内容区 /* End Footer */
前缀规范
s:表示字符串。例如:sName,sHtml; n:表示数字。例如:nPage,nTotal; b:表示逻辑。例如:bChecked,bHasLogin; a:表示数组。例如:aList,aGroup; r:表示正则表达式。例如:rDomain,rEmail; f:表示函数。例如:fGetHtml,fInit; o:表示以上未涉及到的其他对象,例如:oButton,oDate;
函数命名规范
统一使用动词或者动词[+名词]形式,例如:fGetVersion(),fSubmitForm(),fInit();涉及返回逻辑值的函数可以使用is,has等表示逻辑的词语代替动词。
如果有内部函数,使用__f+动词[+名词]形式,内部函数必需在函数最后定义。
对象方法实现
对象方法命名使用 f+对象类名+动词[+名词]形式;例如 fAddressGetEmail
事件响应函数
某事件响应函数命名方式为触发事件对象名+事件名或者模块名+触发事件对象名+事件名,例如:fDivClick(),fAddressSubmitButtonClick()
其它注意事项
所有命名最好使用英语表示。
所有变量名应该明确而必要,尽量避免不必要的容易混淆的缩写。
netease.events.mouse.Handler,而不是 netease.events.mouse.MouseEventHandler。
对应的方法应该使用对应的动词,例如:get/set, add/remove, create/destroy, start/stop, insert/delete, begin/end。
应该避免双重否定意义的变量,例如:bIsNotError, bIsNotFound,不可取。
变量应该在最小的范围内定义,并尽可能的保持最少的活动时间。
循环变量最好在循环中定义。例如for(var i=0,m=10;i++)
尽量避免复杂的条件语句,可以使用临时的boolean变量代替。
一定要避免在条件中执行语句,例如:if((i=3)>2){},不可取。
不要在代码中重复使用相同意义的数字,用一个变量代替