Seajs前端开发规范

时间 2019-11-10

标签 seajs 前端开发规范繁體版

原文原文链接

Seajs简介

SeaJS是一个遵循CommonJS规范的JavaScript模块加载框架，能够实现JavaScript的模块化开发及加载机制。与jQuery等 JavaScript框架不一样，SeaJS不会扩展封装语言特性，而只是实现JavaScript的模块化及按模块加载。SeaJS的主要目的是令 JavaScript开发模块化并能够轻松愉悦进行加载，将前端工程师从繁重的JavaScript文件及对象依赖处理中解放出来，能够专一于代码自己的逻辑。SeaJS能够与jQuery这类框架完美集成。使用SeaJS能够提升JavaScript代码的可读性和清晰度，解决目前JavaScript 编程中广泛存在的依赖关系混乱和代码纠缠等问题，方便代码的编写和维护。css

更多介绍请参考官方主页：http://seajs.org/docs/。html

目录规范

E:\WORKSPACES\MYECLIPSE10\FRONTPROJECTEXAMPLE\WEBROOT前端
│ build.batjava	自动打包压缩的执行文件node
│jquery
├─htmlgit	存放前端展现页面github
│ └─testweb
│ css.htmlnpm
│ test1.html
│
├─js	javascrpt 文件
│ │ cmd.bat
│ │ seajs-config.js	seajs配置文件
│ │ update.bat	更新seajs库的可执行文件
│ │ update.rd
│ │
│ ├─apps	项目脚本文件
│ │ │ package.json	npm打包文件
│ │ │
│ │ ├─base	基础公用的类方法
│ │ │ do.js
│ │ │ in.js
│ │ │ lab.js
│ │ │	业务目录
│ │ └─test
│ │ 1.css
│ │ css.js
│ │
│ ├─otherlib	第三方脚本库
│ │ │
│ │ └─jquery
│ │ ├─jquery
│ │ │ jquery-1.10.2.js
│ │ │ jquery-1.10.2.min.js
│ │ │
│ │ └─jquery-easyui-1.3.4
│ │
│ └─sea-modules	seajs库
│ ├─apps	打包后的业务目录文件
│ │
│ ├─gallery	自带的经常使用库
│ │ ├─handlebars
│ │ │ └─1.0.2
│ │ │ handlebars-debug.js
│ │ │ handlebars.js
│ │ │ package.json
│ │ │ runtime-debug.js
│ │ │ runtime.js
│ │ │
│ │ └─underscore
│ │ └─1.4.4
│ │ package.json
│ │ underscore-debug.js
│ │ underscore.js
│ │
│ ├─jquery
│ │ └─jquery
│ │ └─1.10.1
│ │ jquery-debug.js
│ │ jquery.js
│ │ package.json
│ │
│ └─seajs	seajs核心库
│ ├─seajs
│ │ └─2.1.1
│ │ package.json
│ │ sea-debug.js
│ │ sea.js
│ │ sea.js.map
│ │
│ ├─seajs-style	样式插件
│ │ └─1.0.2
│ │ package.json
│ │ seajs-style-debug.js
│ │ seajs-style.js
│ │
│ └─seajs-text	模版插件
│ └─1.0.3
│ package.json
│ seajs-text-debug.js
│ seajs-text.js
│
├─META-INF
│ MANIFEST.MF
│
└─WEB-INF
│ web.xml
│
├─classes
└─lib

代码规范

模块编写

参照CMD规范。http://seajs.org/docs/#docs 文档的模块编写规范。

命名规范

必须使用 Tab 键进行代码缩进，以节约代码大小(建议设置编辑器的tab为4个空格的宽度)
接口风格

结构	规则	例如
类	驼峰式	ModuleClass()
公有方法	混合式	getPosition()
公有变量	混合式	frameStyle
常量	大写式	DEFAULT_FRAME_LAYOUT

其余建议风格，非必要

结构	规则
私有方法	混合，例子：mixedCase
私有变量	混合，例子：mixedCase
方法（method）参数	混合，例子：mixedCase, mixedCase
本地（local）变量	混合，例子：mixedCase, mixedCase

全部语句结束后，必须使用 ; 号结束
全部变量必须是有意义的英文，严厉禁止拼音
变量容许使用公认英文缩写
类命名必须是驼峰式
常量必须全部单词大写，而且每一个单词间加下划线
枚举类型时，枚举的命名必须有意义，枚举与枚举成员必须以驼峰式
常量和枚举必须在最前端定义，merge 时注意，必须把常量与枚举定义的文件放在文件列表的第一位
变量内的简写单词不能全大写XmlDocument strHtml
"on"只能用做事件的命名
函数开头必须是有意义的动词或动词短语
私有类的变量属性成员建议使用混合式命名，并前面下下划线
临时的全局变量放到一个全局的哈希表里，方便变量回收
全部全局变量必须初始化，尽可能少用全局变量
大括号前面不能有换行符
保留字以及特有的dom属性不能做为变量名

特殊命名约定

前面加 "is" 的变量名应该为布尔值，亦可以使用 "can" "has" "should"
前面加 "str" 的变量名应该为字符串
前面加 "arr" 的变量名应该为数组
前面加 "num" 或 "count" 的变量名应该为数字
"o" 做为局部变量或参数，表示为Object
"e" 做为局部变量或参数，表示为Element
"evt" 做为局部变量或参数，表示为event
"err" 做为局部变量或参数，表示为error
重复变量建议使用 "i", "j", "k" （依次类推）等名称的变量(全世界公认)
能缩写的单词尽可能缩写
避免产生使人误解的布尔值 isNotNumber isNan
处理错误的变量，必须在后面跟着 "Error"
初始化用的函数必须使用 "init" 开头，若是一个页面只有初始化能够单独使用 init()
尽可能作有意义的代码折行，不要让一行代码过长。(HTML 字符串除外)
操做符建议使用空格隔开
函数调用和方法避免使用空白
逗号（,）建议使用空白隔开。
不容许频繁使用 previousSibling 和 nextSibling

词法结构

普通代码段应该看起来以下：

while(!isDone){
doSomething();
isDone = moreToDo();
}
if 语句应该看起来像这样：

if(someCondition){
statements;
}elseif(someOtherCondition){
statements;
}else{
statements;
}
for 语句应该看起来像这样：

for(initialization; condition; update){
statements;
}
while 语句应该看起来像这样：

while(!isDone){
doSomething();
isDone = moreToDo();
}
do ... while 语句应该看起来像这样：

do{
statements;
}while(condition);
switch 语句应该看起来像这样：

switch(condition){
case ABC:
statements;
  // fallthrough
case DEF:
statements;
  break;
default:
statements;
  break;
}
try ... catch 语句应该看起来像这样：

try{
statements;
}catch(ex){
statements;
}finally{
statements;
}
单行的 if - else，while 或者 for 语句也必须加入括号：

if(condition){ statement;}
while(condition){ statement;}
for(intialization; condition; update){ statement;}

注释规范

具体的文档示例能够参考 https://github.com/senchalabs/jsduck/wiki

@author ：做者
@class ：类
@deprecated：标记此方法属性或者类不同意使用，在升级过渡的时候需兼容以前的API时特别有用。
@example：给类或者方法添加一个代码范例，jsduck不只会给代码着色，还能给代码生成一个代码编辑器，编辑代码后可实时预览，使用@example须要四个空格的缩进。
@extends ：标记一个类继承自另外一个类，生成后会有一个类型继承体系陈列在文档视图的右侧。
@cfg ：构造器的配置项，并在其后跟随"{className}"，再跟随参数名。

范例：@cfg {String} fieldName配置项的描述。

@return ：与@cfg 相似，标记一个函数成员调用事后的返回类型。

范例：@return {Number} 文字描述

@param：与@cfg 相似，给一个函数成员标记其所需的参数类型和描述，若是参数类型为多种能够用"/"分割，如须要给参数进行更详细描述还能使用"[param.member]"描述符。

范例：@param {Number/String} fieldName

范例：@param {String[]} fieldName

范例： /**
* @cfg {Object} opt
* @cfg {Number} [opt.age]
* @cfg {Number} [opt.name=0]
*/

@event ：标记一个事件，随后一般会跟随@param标签给事件回调函数声明参数的说明。
@inheritdoc：在其后跟随Class#member，经常使用在子类覆盖父类成员后，子类注释块还需继续使用父类注释的状况下使用。
@private ：将成员标记成私有，虽然也有@public 但若是不特殊标明即为公有。
@protected ：将成员标记成受保护的。
@static :将成员标记成静态的，静态成员也会在文档中进行分类展现。
@img ：在文档注释中连接一张图片，让文档变得更具可读性。
@link ：在文档注释中标记某个类或类成员的锚点。

一个示例项目

该示例项目SVN : http://192.168.1.101:801/svn/998597/FrontProjectExample

环境配置

第一步：安装文件下载

Node.js http://nodejs.org/

第二步：执行安装

$ npm install spm -g

$ npm install spm-chaos-build -g

关于 spm 和 spm-chaos-build的详细介绍能够参考

https://github.com/spmjs/spm2

https://github.com/edokeh/spm-chaos-build

第三步：建立业务模块

3.1：建立js文件

在js/apps/test/目录下建立module1.js内容为：

3.2：建立html文件

在html/test/目录下建立module1.html内容为:

注意红色框的修改（与js文件名和目录一致）。

预览效果：

此时要保证seajs-config.js的production配置属性为flase,以下图：

3.3：修改package.json

修改js/apps目录下的package.json，修改以下红色框中的信息。

第四步：构建打包项目

双击根目录下的build.bat,可完成自动打包。

查看seajs-config.js文件

自动生成seajs的map

预览效果以下：

请注意二者之间的区别。

总结

为何要使用seajs

管理开发和打包的有效的管理规范。

Require是异步加载的。

相信看完下面两篇文章，能够了解Require为何是异步加载的了，若是你须要依赖加载的文件加载器，请选择In.js: http://project.benben.cc/In/。

https://github.com/seajs/seajs/issues/259

https://github.com/seajs/seajs/issues/260

Export的输出不能是函数返回值

https://github.com/seajs/seajs/issues/242

外部js库或样式的调用方法

强烈建议使用In.js 在seajs.use以前把须要的JS库加载进来，使用In.js主要有两个缘由

能加载管理CSS文件
加载CSS文件时不会出现多个css重复加载的问题（反面教材:DO.JS）

不建议使用库中自带的。Require模块进行加载在模块中使用（do，labjs, in）进行加载，缘由：

https://github.com/seajs/seajs/issues/993

模块内的js和css是自动打包的

前文已经演示过，使用 pm-chaos-build 进行打包的过程，详细请看：

https://github.com/edokeh/spm-chaos-build-example
按照注释规范书写，能够自动生成文档。

https://github.com/senchalabs/jsduck

这是一个能够把你的代码翻译成.Extjs 文档的好工具，可是前提要按照规则写代码。代码规则

https://github.com/senchalabs/jsduck/wiki/Guide
测试是有必要的

http://llying.iteye.com/blog/258605

来自： http://cxc3214.blog.163.com/blog/static/23812806201310145015273/