注册 登录  
 加关注
   显示下一条  |  关闭
温馨提示!由于新浪微博认证机制调整,您的新浪微博帐号绑定已过期,请重新绑定!立即重新绑定新浪微博》  |  关闭

断尘居

温柔的男人像海洋。

 
 
 
 
 

日志

 
 

JavaScript建议规范  

2010-10-06 20:41:45|  分类: JS / jQuery |  标签: |举报 |字号 订阅

  下载LOFTER 我的照片书  |

一.  概述

为了统一前端开发的代码风格,以便后续代码的管理和维护,在使用前端开发框架时请遵循本文档制定的规范编写代码

本文档涉及的规范主要包含四个方面:注释规范、命名规范、模型、控件规范

二.  注释规范

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

1.     文件注释

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

  • 说明部分:描述文件实现的功能、模块或接口等,如有需要增加使用说明或者范例。
  • 作者部分:记录文件的开发者名称和联系方式,用以后续的维护或者交流沟通等。
  • 依赖部分:记录当前文件直接依赖的其他文件,便于工具构建依赖关系。

注释范例如下图所示:

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

2.     接口注释

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

  • 说明部分:说明当前接口的功能,如有需要可增加使用说明或者范例。
  • 输入部分:说明输入数据的类型及含义。
  • 输出部分:说明输出数据的类型及含义。

注释范例如下图所示:

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

另外接口的注释包括私有接口注释和公共接口注释,其中私有接口注释用“/*  */”公共接口用“/**  */”这个同Java中的注释规范。

3.     注释

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

  • 功能描述部分:描述类所代表的对象及基本功能,如需要可增加使用说明或范例。
  • 继承关系部分:说明类的父类,以便于代码的回溯。
  • 初始数据部分:类对象在实例化时可接收这些数据做为初始信息。

注释范例如下图所示:

JavaScript规范建议 - genify - ajaxer 

三.  命名规范

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

1.     命名空间

规则:小写字母

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

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

范例:op.tsk, lv.sys

2.     私有属性/接口

规则:“__”+描述,即增加前缀“__”(两个下划线)

说明:此类属性/接口仅会在当前对象或者子类内使用,对于其他对象不可见,在系统发布时会对此类变量做混淆,因此在选择名称时以便于理解为主。

范例:如下例所示的__appName,__getVersion等等

JavaScript规范建议 - genify - ajaxer 

3.     公共属性/接口

规则:“_$”+描述,即增加前缀“_$”

说明:此类属性或者接口可以为外部程序直接使用,系统发布时如果所有js统一发布则该类属性或者接口也会做混淆处理,因此在选择名称时以便于理解为主。

范例:如下例所示的_$hoverElement

JavaScript规范建议 - genify - ajaxer

4.     对象

规则:“_$$”+描述,即增加前缀“_$$”

说明:此类对象可在程序任何地方使用,系统发布时如果所有js统一发布则该类名称也会做混淆处理,因此在选择名称时以便于理解为主。

范例:如下例所示的_$$Card

JavaScript规范建议 - genify - ajaxer 

5.     临时变量/参数

规则:“_”+描述,即增加前缀“_”(单个下划线)

说明:此类名称仅在当前接口使用,系统发布时做混淆处理,因此在选择名称时以便于理解为主。

范例:如下例所示的_event,_tsk

JavaScript规范建议 - genify - ajaxer

四.  模型

JavaScript中本身没有的概念,在实际应用中我们在JavaScript中引入的概念主要出于以下几方面考虑:

  • 利用面向对象的优势
  • 控件之间的低耦合性
  • 代码的重用
  • 代码的管理维护

对于JavaScript模型的实现有很多方式,通过不断的实践我们并结合公司内部的库,项目中采用模型设计的请遵循以下规范。注:请按照以下顺序创建

1.      的定义

定义统一使用C接口,范例如下

JavaScript规范建议 - genify - ajaxer

2.     的继承

通过1中定义的会具备扩展接口,可以从其他继承,范例如下

JavaScript规范建议 - genify - ajaxer

3.     的初始化

的初始化接口统一为_$initialize

  • 接受的构造参数做为输入
  • 如果需要调用父类的_$initialize,用this._$super();
JavaScript规范建议 - genify - ajaxer

4.     接口的实现

根据的需要实现其他接口,在子的其他接口中如果需要掉父的同名接口采用以下方式

JavaScript规范建议 - genify - ajaxer

五.  控件规范

JS库中的控件主要分为UI控件和通用控件两类,两类控件均遵循本文档所定的规范制作,两者的最大区别在于UI控件包含了页面结构和呈现样式信息,而通用控件则更多的是关注于控件的内部逻辑,与页面的结构和呈现无关。

所有代码必须符合前端开发规范制定的的标准。

1.     控件结构

XHTML中标签的结构类似,JS库中的控件也包含以下几部分:

1.1.  属性

控件的组成部分,如一个UI控件都会有页面相关的节点与之关联,这里的节点属性即为控件的一个属性。

控件的配置信息,这部分信息可以是控件预设的私有配置信息,也可以是控件实例化时外部输入的配置信息。

1.2.  接口

控件统一对外提供用来完成某一功能或者读写控件内部数据的方法,从控件的角度来看为被动式。

1.3.  事件

控件在执行特定逻辑时会给外界发送一个消息,让控件的使用者能能够知道当前控件的状况以便能及时调整系统其他控件的行为,而这个消息机制就是控件里所设计的事件。控件使用者是否添加了相应的事件处理逻辑不会影响到控件本身的功能,从控件的角度来看为主动式。

2.     控件创建

我们这里指的控件是指在实际项目中频繁使用并且与项目低耦合的,因此控件的创建同样也遵循模型中的四个步骤

3.     控件范例

控件范例见JS库中utilui目录下的各控件实现文件

4.     控件使用

控件的使用请注意以下几点:

4.1   定义外观

项目中需要如果需要对控件外观做更新,则可直接在项目的样式文件中做定义,对于控件更新部分的样式定义遵循以下规则:

  • 使用项目ID来提升自定义样式的优先级
  • 为控件定义项目相关的样式类名称
  • 自定义控件开放的样式
JavaScript规范建议 - genify - ajaxer

4.2   引入控件

从库中获取控件源码并在页面中引入

JavaScript规范建议 - genify - ajaxer

4.3   使用控件

控件的使用可以参阅每个控件目录下的test.html文件,每个控件的详细信息说明可参阅库文档中控件相关的文档

JavaScript规范建议 - genify - ajaxer
  评论这张
 
阅读(2145)| 评论(1)
推荐 转载

历史上的今天

在LOFTER的更多文章

评论

<#--最新日志,群博日志--> <#--推荐日志--> <#--引用记录--> <#--博主推荐--> <#--随机阅读--> <#--首页推荐--> <#--历史上的今天--> <#--被推荐日志--> <#--上一篇,下一篇--> <#-- 热度 --> <#-- 网易新闻广告 --> <#--右边模块结构--> <#--评论模块结构--> <#--引用模块结构--> <#--博主发起的投票-->
 
 
 
 
 
 
 
 
 
 
 
 
 
 

页脚

网易公司版权所有 ©1997-2017