内容目录

开发规范

目的与原则

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

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-