团队规范文档
文章目录
目录结构
- 引入亚信UED的基础前端框架，包括JS底层库，UI样式库，开发规范，自动化工具，团队知识库
- 引入cmd,seajs,nodejs,grunt,npm,markdown等
细化各级目录分类，方便清晰管理，考虑文件的部署压缩合并
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56
my-project-name │ ├── res │ ├── conf // ajax数据接口，seajs配置，Grunt配置，npm包管理 │ ├── ai │ │ ├── aijs // JS库，包含基础扩展以及工具方法 │ │ ├── aiui // UI库，包含样式模块以及交互组件 │ │ ├── aicg // 编码规范[MD]，包含各种书写规范以及校验工具 │ │ ├── aimd // 知识库[MD]，包含新人成长，以及常见疑难问题解决方案 │ │ └── aiat // 工具库[MD]，包含前端开发以及自动化部署工具 │ ├── scripts │ │ ├── lib // 基础框架 jQuery, Zepto, Handlebars, extjs │ │ ├── fn // 功能库 D3.js, Map.js │ │ ├── ui // 插件库 zTree, omGrid, My97, artDialog, autocomplete, validform │ │ └── page │ │ ├── common // 公用的模块 │ │ ├── login // 登录 │ │ ├── search // 搜索 │ │ └── business // 办理 │ ├── models │ │ ├── widget // 插件模块 │ │ │ └── collapse │ │ │ ├── data // 数据 │ │ │ ├── tpl // 模版 │ │ │ └── hbs // 模版预编译 │ │ │ │ │ └── page │ │ ├── common // 公用的模块 │ │ │ ├── data │ │ │ ├── tpl │ │ │ └── hbs │ │ ├── login // 登录 │ │ └── search // 搜索 │ ├── styles │ │ ├── globe // 全局样式，Less生成主题文件 │ │ │ ├── default │ │ │ │ └── globe.css // 默认主题 │ │ │ ├── blue │ │ │ │ └── globe.blue.css // 蓝色主题 │ │ │ └── dark │ │ │ └── globe.dark.css // 黑色主题 │ │ └── page │ │ ├── login │ │ │ └── login.css // 登录页样式 │ │ └── search │ │ └── search.css // 搜索页样式 │ │ │ ├── page │ │ ├── search.html // 搜索页面 │ │ └── business │ │ ├── query.html // 查询页面 │ │ └── pay.html // 充值页面 │ │ │ └── index.html │ └── login.html
命名规范
CSS 类名
- 保持 Class 命名为全小写，可以使用短划线（不要使用下划线和 camelCase驼峰式命名）
- 短划线应该作为相关类的自然间断。(例如，
.btn和.btn-danger)。 - 避免过度使用简写。.btn 可以很好地描述 button，但是 .s 不能代表任何元素。
- Class 的命名应该尽量短，也要尽量明确。
- 使用有意义的名称；使用结构化或者作用目标相关，而不是抽象的名称。
- 命名时使用最近的父节点或者父 class 作为前缀
- 使用 .js-* classes 来表示行为(相对于样式)，但是不要在 CSS 中包含这些 classes。
1 2 3 4 5 6 7 8 9 |
/* Bad example */
.t { ... }
.red { ... }
.header { ... }
/* Good example */
.tweet { ... }
.important { ... }
.tweet-header { ... } |
JavaScript 变量命名
- 标准变量采用驼峰标识
- 使用的ID的地方一定全大写
- 使用的URL的地方一定全大写, 比如说 reportURL
- 涉及Android的，一律大写第一个字母
- 涉及iOS的，一律小写第一个，大写后两个字母
- 常量采用大写字母，下划线连接的方式
- 构造函数，大写第一个字母 ``` var thisIsMyName;
var goodID;
var AndroidVersion;
var iOSVersion;
var MAX_COUNT = 10;
function Person(name) { this.name = name }
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
####HTML，TPL文件命名
- 多个单词组成时，采用中划线连接方式，比如说：error-report.html
####CSS，LESS文件命名
- 多个单词组成时，采用中划线连接方式，比如说: retina-sprites.scss
####JavaScript，JSON文件命名
- 多个单词组成时，采用中划线连接方式，比如说：账号模型文件 account-model.js
##HTML
####基础设施
- 文档声明，文件应以“<!DOCTYPE ......>”首行顶格开始，推荐使用html5文档类型
<!DOCTYPE html>
<html>
<head>
</head>
</html>
- 语言种类，默认声明文档使用中文 |
1
|
- 页面编码，必须申明文档的charset编码，且与文件本身编码保持一致，推荐使用utf-8编码 |
1
|
- IE兼容模式，默认使用最高浏览器的渲染模式，考虑向后兼容 |
1
|
- 样式和脚本，引入 CSS 和 JavaScript 时不需要指明 type |
<!DOCTYPE html>
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
#### 书写格式
- 代码保持简洁的树形结构，必须使用四个空格的TAB键来进行代码缩进
- HTML标签名、属性和值全部小写，属性不能为空且必须加双引号
- 不要使用` `进行缩进
- 不要使用行内样式
- 不要在内联元素中嵌入块级元素
- 不要在自动闭合标签结尾处使用斜线
- `<img src="photo.png" alt="头像">`
- 不要在`Boolean`属性值中声明取值的属性
- `<input type="text" disabled>`
- HTML 属性应该按照特定的顺序出现以保证易读性
- `id`
- `class`
- `name`
- `data-*`
- `src`,`for`,`type`,`href`
- `title`, `alt` |
1 2 3 4 5 6 7 8 9 10 11 12 13 |
#### 语义优化 - 根据网页中某种类型的内容，使用特定HTML语义化的标签编写页面结构 - 对a元素提供title属性，img提供alt属性，加强"资源型"内容的可访问性 - 当空标签使用背景图时，必须加上相对应的文字说明，并按需隐藏文字，加强"不可见"内容的可访问性 - 使用div代替table进行布局，但是表现具有明显表格的数据，table还是首选 - 实用高于完美，尽量的遵循 HTML 标准和语义，但是不应该以浪费实用性作为代价 ## CSS #### 基础设施 - CSS文件顶格位置申明文档的编码charset，推荐使用UTF-8编码 |
@charset “utf-8”;
1 2 3 4 5 |
- 样式表中的中文字体使用unicode转码
font-family: Tahoma, "\5fae\8f6f\96c5\9ed1", "\5B8B\4F53";
- 使用clearfix或overflow清除子元素的浮动，而不是空标签 |
.clearfix:after{ visibility:hidden; display:block; font-size:0; content:” “; clear:both; height:0; } .clearfix{ zoom:1; }
1
|
- 针对某个浏览器写的样式或某个浏览器BUG的样式，必须加上注释说明 |
.clearfix{ zoom:1; /* for IE6 IE7 */ }
1
|
- 不使用影响页面性能expression表达式与filter，实现必要的特殊效果时，允许使用 |
/* expression */ .class{width:expression(this.width>100?‘100px’:‘auto’);}
/* filter */ .class{filter:alpha(opacity=50);}
1 2 3 4 5 6 7 8 |
#### 书写格式 - 使用四个空格的TAB键来进行代码缩，保证代码在各种环境下显示一致 - 为了代码的易读性，在每个声明的左括号前增加一个空格。 - 声明块的右括号应该另起一行 - 选择器、属性和值都使用小写，并且为选择器中的属性取值添加引号`input[type="text"]` - 使用组合选择器时，保持每个独立的选择器占用一行 - 使用逗号分隔的取值，都应该在逗号之后增加一个空格。比如说`box-shadow` - 最后一个属性值也以分号结尾，避免后期对维护带来的麻烦 |
.selector, .selector-secondary, .selector[type=“text”] { padding: 15px; margin-bottom: 15px; box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff; }
1 2 3 |
- 所有的十六进制值都应该使用小写字母，并且使用缩写方式 `color:#fff;` - 当值为0时省略单位 `margin:0;` - `z-index`一般以5为一个步长（如50,55,60），方便以后增加或修改 |
.ui-box1 { z-index: 50; } .ui-box2 { z-index: 55; }
1
|
- 省略url引用中的引号，其他需要引号的地方使用双引号 |
.ui-box { background:url(bg.png); } .ui-box:after { content:“.”; }
1
|
- 先写带有浏览器私有标志的，并且通过缩进使取值垂直对齐以便多行编辑。 |
.ui-box { -webkit-box-shadow:0 0 0 #000; -moz-box-shadow:0 0 0 #000; box-shadow:0 0 0 #000; }
1 2 3 4 |
- 不建议使用`!important`，不建议使用`@import`，
- 原则上不允许使用Hack，不兼容问题可以通过改变方法和思路来解决，对于浏览器自身的缺陷，可以允许使用适当的Hack
- 当使用属性简写时你必须设置所有取值，常见的属性滥用包括
- `padding`,`margin`,`font`,`background`,`border`,`border-radius` |
/* Bad example */ .element { margin: 0 0 10px; background: red; background: url(“image.jpg”); border-radius: 3px 3px 0 0; }
/* Good example */ .element { margin-bottom: 10px; background-color: red; background-image: url(“image.jpg”); border-top-left-radius: 3px; border-top-right-radius: 3px; }
1 2 |
- 根据属性的重要性按顺序书写
- Positioning 位置 > Box model 盒模型 > Typographic 排版 > Visual 外观 > Misc 混杂 |
.declaration-order { /* Positioning 位置*/ position: absolute; top: 0; right: 0; bottom: 0; left: 0; z-index: 100;
/* Box-model 盒模型*/ display: block; float: right; width: 100px; height: 100px;
/* Typography 排版*/ font: normal 13px “Helvetica Neue”, sans-serif; line-height: 1.5; color: #333; text-align: center;
/* Visual 外观*/ background-color: #f5f5f5; border: 1px solid #e5e5e5; border-radius: 3px;
/* Misc 混杂*/ opacity: 1; }
1 2 |
#### 代码组织 - 以模块为单位组织代码，使用继承以及提取公共样式，提高代码复用率 |
标题
1 2 3 4 5 6 |
## JavaScript #### 缩进,分号,换行,空格 - 4个空格保持代码缩进 - 在语句末尾使用分号结束，清楚语句的起止位置 - 多于120个字符应换行，优先在左花括号后、操作符后进行换行； - if else前后留有空格 |
if (typeof state === “undefined” || typeof state.cdnrejected === “undefined” || state.cdnrejected !== true) { url = “http://pub.state.com/qqfind/js/location4.js"; } else { url = “http://find.state.com/js/location4.js"; }
1 2 3 4 5 6 7 8 9 |
#### 空行 - 方法之间加 - 单行或多行注释前加 - 逻辑块之间加空行增加可读性 #### 括号对齐 - 括号前后有空格， 花括号起始 不另换行，结尾新起一行 - 花括号必须要， 即使内容只有一行， 决不允许右边第二种情况 - 涉及 if for while do...while try...catch...finally 的地方都必须使用花括号 |
// Good if (condition) { doSomething(); }
// Bad if (condition) doSomething(); doSomethingElse();
1 2 3 |
####变量声明 - 所有函数内的变量声明应该放在函数内头部，只使用一个 var(多了JSLint报错)， 一个变量一行， 在行末跟注释 - 优先使用单引号（'）而不是双引号（"）表示字符常量 |
function doSomethingWithItems(items) {
var value = 10, // 注释 result = value + 10, // 注释 name = ‘rose’, // 注释 i, // 注释 len; // 注释
for (i=0, len=items.length; i < len; i++) { doSomething(items[i]); } }
1 2 3 4 5 |
####函数声明 - 函数声明 和 函数表达式 的不同，函数表达式 的（）前后必须有空格，而函数生命 在有函数名的时候不需要空格， 没有函数名的时候需要空格。 - 函数调用括号前后不需要空格 - 立即执行函数的写法, 最外层必须包一层括号 - "use strict" 决不允许全局使用， 必须放在函数的第一行， 可以用自执行函数包含大的代码段, 如果 "use strict" 在函数外使用， JSLint 和 JSHint 均会报错 |
function doSomething(item) { // do something }
var doSomething = function (item) { // do something }
// Good doSomething(item);
// Bad: Looks like a block statement doSomething (item);
// Good var value = (function() {
// function body return { message: “Hi” } }());
// Good (function() { “use strict”;
function doSomething() { // code }
function doSomethingElse() { // code }
})();
1 2 3 |
####undefined使用 - 永远不要直接使用undefined进行变量判断 - 使用字符串 "undefined" 对变量进行判断 |
// Bad var person; console.log(person === undefined); //true
// Good console.log(typeof person); // “undefined”
1
|
####Object对象 |
// Bad var team = new Team(); team.title = “AlloyTeam”; team.count = 25;
// Good semi colon 采用 Followed by space 的形式 var team = { title: “AlloyTeam”, count: 25 };
1
|
####Array数组 |
// Bad var colors = new Array(“red”, “green”, “blue”); var numbers = new Array(1, 2, 3, 4);
// Good var colors = [ “red”, “green”, “blue” ]; var numbers = [ 1, 2, 3, 4 ];
1 2 3 4 |
####switch - 花括号必须要， 即使内容只有一行; - switch和括号之间有空格， case需要缩进; - break之后跟下一个case中间留一个blank line; |
switch (condition) { case “first”: // code break;
case “third”: // code break;
default: // code }
1 2 3 4 |
####for - 普通for循环, 分号后留有一个空格， 判断条件等内的操作符两边不留空格 - 前置条件如果有多个，逗号后留一个空格 - for-in 一定要有 hasOwnProperty 的判断， 否则 JSLint 或者 JSHint 都会有一个 warn |
var values = [ 1, 2, 3, 4, 5, 6, 7 ], i, len;
for (i=0, len=values.length; i<len; i++) { process(values[i]); }
var prop; for (prop in object) {
// 注意这里一定要有 hasOwnProperty 的判断， 否则 JSLint 或者 JSHint 都会有一个 warn ！ if (object.hasOwnProperty(prop)) { console.log(“Property name is ” + prop); console.log(“Property value is ” + object[prop]); } }
1 2 3 4 5 6 7 |
#### 其他 - 避免使用`a==b`, `a!=b`， 推荐用严格比较条件 `a===b`, `a!==b` - 非特殊业务， 禁用`eval`,`with` ##注释规范 ####HTML 注释 - 代码说明的注释方法，采用标签闭合的写法，与HTML标签保持格式统一 |
1
|
- 代码本身的注释方法，单行代码的注释也保持在同行，两端空格；多行代码的注释起始和结尾都另起一行并左缩进对齐 |
1 2 3 4 5 6 |
- 注释在IE6中的BUG
- 如果两个浮动元素之间存在注释，那么可能导致布局错位或文字的BUG
- 通常这种情况，把注释去掉是最好的解决方案
####CSS 注释
- 单行注释，写在被注释对象的上一行，对属性及值的注释写于分号后 |
/* 单行注释文字 / .ui-box { border: 1px solid #ccc; } .ui-box-head{ height:20px; line-height:20px;/ 这里是对line-height的一个注释 */ overflow:hidden; }
1
|
- 块状注释，用于布局结构或模块，注释保持统一的缩进对齐，前面留空一行 |
/* * 块状注释文字 * 块状注释文字 */ .ui-box {} .ui-box-head {} .ui-box-head .ui-box-head-title{} .ui-box-container{}
1 2 3 4 5 |
####JavaScript 注释
- 单行注释
* 双斜线后，必须跟注释内容保留一个空格；
* 可独占一行, 前边不许有空行, 缩进与下一行代码保持一致；
* 位于一个代码行的末尾，双斜线距离分号四个空格，双斜线后始终保留一个空格 |
// Good if (condition) {
// if you made it here, then all security checks passed allowed(); }
var zhangsan = “zhangsan”; // 双斜线距离分号四个空格，双斜线后始终保留一个空格
1 2 3 |
- 块状注释
* 注释代码最少三行，保持统一的缩进，前面留空一行
* 用于难于理解或者存在错误的代码段，也适用于HACK代码和逻辑较强的代码注释 |
/* * 注释内容与星标前保留一个空格 */
1 2 3 |
####JsDoc 注释 - JsDoc 是一个根据注释规范自动生成文档的工具 - 详细的文档规范可参考 [usejsdoc.org](http://usejsdoc.org/) |
/** * here boy, look here , here is girl * @method lookGril * @param {Object} balabalabala * @return {Object} balabalabala */ ```
####UPDATE
- 2014-08-20
* 细化HTML,CSS范内容目录，和JavaScript保持一致
* 引入代码格式化和校验工具
文章作者 ZHIKING
上次更新 0001-01-01