开发规范

目的与原则

为了整体代码风格统一,思想一致,所有参与本项目的开发者须了解并遵守本文的。

elf+js项目旨在积累大量的JavaScript常用基础方法,解决开发中浏览器兼容性问题,形成一套组织结构合理功能丰富的基础库。并在此之上通过易用性的设计,简化大多数常用方法的入口书写方式,给使用elf+js基础库的应用开发者带来愉悦的开发体验。

所以开发elf+js项目需要遵循以下原则:

  • 针对jslib基础库
    1. 每个设计的功能解决单一的一类问题(单一职责);
    2. 所设计的功能都只解决共性问题,不因为业务特定问题设计新功能;
    3. 每一类功能由一个类(JavaScript对象或构造器)覆盖;
  • 针对elf易用性封装;
    1. 不增加新功能,只完成对jslib中的易用性封装;
    2. 缩短jslib中常用方法的调用入口;
    3. 包含jslib的所有功能但不覆盖原有接口;
    4. 只为常用方法设计;

文件组织规范

  1. 每个类一个文件,除非该类是静态类且对应一类功能的具体调用方法相关性不高时,可以把调用方法的文件分散到同名子级目录中;
  2. 文件名同类名/方法名(包括大小写),但不需要包含完整的命名空间路径;
  3. 解决同一领域问题的类划分为一个包,即文件夹;
  4. 如果代码内容只是一个执行过程(如解决兼容性问题)时,则文件命名以“~”开头,并取符合内容意义的文件名;

代码规范

命名规范

[ jslib ]

  1. 包/类/方法/变量/常量等原则上参照Java的命名:
    1. 包名全部小写,原则上尽量短,只能使用一个单词或缩写单词;
    2. 类名首字母大写,多单词驼峰;
    3. 方法名首字母小写,多单词驼峰;
    4. 变量名同方法名;
    5. 常量全部字母大写,多单词下划线“_”连接;
    6. 所有命名须使用尽量符合对应意义的英文单词或缩写,禁止使用汉语拼音;
  2. 顶级命名空间为js.
  3. js之下设置二级功能包,对应领域相关问题,任何一个类都必须定义在二级命名空间之下,即js命名空间下禁止放置任何类;
  4. 二级包下可以放置类,在类较多(原则上超过30个)时,也可以划分更深层次的包,此级开始允许包内同时存在包和类;
  5. 单纯的函数功能必须挂靠在一个静态类之下,以表明相关的功能相关性,禁止直接在包下直接申明函数;

[ elf ]

elf由于不存在真正的实体,规范相对宽松。

书写规范

(to be writen…)

注释

注释不仅写给别人看,也是写给自己看的。

文档注释

我们使用ext-doc来生成基于文档注释的API手册,所以对每一个类和方法都需要编写文档注释。

代码注释

缩进和对齐

  1. 使用[TAB]作为缩进字符;
  2. 如需要对齐赋值变量表,请使用空格而非[TAB];

版本控制

分支管理

master
主干分支,和正式发布版本保持完全一致
dev
开发分支,所有开发都必须使用非master的分支
hotfix
紧急修复分支,当某个产品线发现有线上问题急需修复时,从master创建一个临时修复分支来进行修复

发布周期

  1. 收集需求(wish-list)和问题反馈(bug-list),评估一份两周之内可以完成的且相关性较高的工作内容,在dev分支上开始开发;
  2. 开发结束并测试通过后合并到master分支准备发布;

版本号相关

  1. 对外发布使用三位版本号,如0.3.0
  2. 在下一版本要进行当前功能问题修复或相关功能小范围改进时,第三位版本号+1;
  3. 在下一版本中部分接口发生调整或增加新功能时,第二位版本号+1;
  4. 在整体大范围接口变动或组织结构重构时,首位版本号+1;

新版本发布步骤

在确认一个版本的代码开发且测试完成后,进入以下发布的过程:

Github操作

  1. merge相关版本的开发分支到主干分支(master),如有冲突需要全部解决,并push主干分支到github仓库;
  2. 打版本标签(tag),格式为v-x.x.x,并push标签到github仓库;

版本文件发布

  1. 使用jslib-builder工具对开发完成的代码(包括jslib和elf)进行发布打包,包含源码文件和使用GCC压缩的文件,另使用7z工具对压缩后的文件再进行Gzip压缩,最终得到三个文件:
    • elf-x.x.x.js
    • elf-x.x.x-min.js
    • elf-x.x.x-min.js.gz
  2. 在Google code上的elfjs项目主页下载页面中分别添加以上三个文件的下载;

网站内容更新

elf+js的网站项目(elfjs.github.com)也放在github上管理,大多数网站内容更新都需要涉及。例外的两个是:

所以网站内容更新主要是这三块内容。

关于家API文档:

  1. 使用ext-doc生成API文档(后续会升级到使用jsduck);
  2. 使用ftp或ssh工具将线上的latest文件夹改名为之前版本号;
  3. 上传新生成的文档文件到latest文件夹;

关于发布日志和下载:

  1. 编辑/_config.yml文件,修改release部分,移动之前的当前发布版本到历史版本中,在原位置添加新版本的发布信息,包括版本号、发布日期和SHA1验证码等;
  2. /_posts目录添加一个发布日志文件(可复制之前的然后修改版本号得到),编辑发布相关的内容;
  3. 本地运行jekyll并预览各页面和链接是否正常,验证后提交所有文件推送到github仓库自动更新在线页面。

关于在线打包工具:

  1. 更新jslib-builder项目中的仓库子项目到master最新提交;
  2. 删除原有线上仓库文件;
  3. 使用ftp或ssh工具将新的仓库文件上传到线上;

-EOF-