云积分前端规范

2015-03-18 本文已影响127人松鼠闹IT

1.规范说明

此为前端开发团队遵循和约定的代码书写规范，意在提高代码的规范性、扩展性、可维护性、阅读性，提高工作效率，提升个人技术。

此规范为参考规范，不全是硬性要求，部分硬性约定见下一条书写规范，统一团队编码规范和风格。让所有代码都是有规可循，并且能够得到沉淀，减少重复劳动。

1.1结构说明

-- 项目结构
----|---- public公共静态文件夹
----|----|---- CSS文件夹
----|----|---- JS文件夹
----|----|----|---- libs插件文件夹
----|----|---- images文件夹

2.书写规范

2.1 样式与内容分离

2.1.1 项目结构

-——  根目录  
    |-——- 功能目录  
        |-——- index.html //功能入口页面  
    |-——- public/  
        |-——- CSS/  
            |-——- 对应功能样式目录  
        |-——- JS/  
            |-——- 对应功能JS目录

2.1.2 重构步骤

index.html页面中的全部样式关联 class="xxx" 注：制作静态页面的时候文件中不包含任何一个id="XXX"
为 index.html 书写CSS style [到这里页面重构完成]
开始 index.html 书写JS交互文件，使用 id 和 class定位元素来进行交互，如果是单个元素操作 id 名的前面加上 js，如果是操作元素的 class 则给 class 加上 js- 前缀 [到这里页面交互完成]

2.1.3 命名规范

文件以及文件夹：全部用英文小写字母+数字或者是连接符“-、_”，不可出现其它字符，例如：...、---...
文件：调用 /libs 文件需包含版本号，压缩文件需包含 min 关键词，其它插件则不包含，例如： /libs/jquery.1.9.1.js、fileuploader.js
ID名：匈牙利命名法 & 驼峰式大小写，如果是要获取某个ID的value，那这个ID名最好和后端提供的接口字段名一模一样，为了方便查看
如：firstName aList
Class名：全部小写，用-连接符
如：top-item main-box
尽可能用语义明确的单词命名

2.1.4 格式&编码

文本文件： .xxx UTF-8(无BOM)编码
图片文件： .png png-24或者png-8（根据情况而定） .jpg
动态图片： .gif

2.2 CSS细化规范

2.2.1

-—— /css/
    |-——- base.css  CSS全局文件
    |-——- 功能样式目录

2.2.1 文件说明

base.css 这个文件包含了CSS reset部分、各个模块的样式、各种margin padding width height...补丁
功能样式目录中包含了各个功能的样式，目录按照页面目录来分层
为了方便查看页面引入的CSS文件，不建议使用 @import

2.2.2 CSS注释格式约定

/*
@name: 文件名
@description：文件描述
@require（可选）： 依赖哪个文件
@author：作者
*/

2.2.3 CSS嵌套规则

/*推荐嵌套层级*/
.ui-icon-rarr{}
.ui-icon-larr{}
.ui-title{}
.ui-nav .ui-list{}
.ui-table .ui-list{}

/* 不推荐 */
.ui-icon-rarr{}
.ui-icon-larr{}
.ui-title{}
.ui-list{}
.ui-nav{}

2.2.4 补充说明

由于现阶段我们还未使用 CSS预编译工具 ，因此在开发的时候我们展示只考虑CSS的目录结构，后期如果我们使用到了 CSS预编译工具 我们就需要有一个预编译文件对应的目录，如 LESS SASS，编译我们可以依靠自动化构建工具来处理

2.3 HTML细化规范

2.3.1 HTML注释格式约定

<div id="header">
    <div class="xxx"><span></span></div>
</div> <!--头部结束-->

HTML换行缩进必须清晰，采用四个空格，如果觉得按空格麻烦，可以在编辑器将 Tab 键设为四个空格

2.3.2 第一行统一使用HTML5标准

<!DOCTYPE html>
<html dir="ltr" lang="zh-CN">
<head>
  <meta charset="utf-8" />
  <title>极客公园 | 创新者社区</title>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
  <link rel="shortcut icon" href="favicon.ico">

标签的使用就不在这里备注了，避免使用过时的标签，统一标准闭合

2.4 JS细化规范

2.4.1 JS文件结构

-—— /js/
|-——- /libs/  使用到的JS插件以及库文件夹
|-——- base.js 全局函数和变量文件
|-——- api.js 存放所有的接口调用函数
|-——- 功能JS目录 对应视图文件的目录

每一个页面中的JS文件建议单独写一个，文件以及文件目录对应视图文件的目录，方便查找以及维护
建议将接口调用写成一个函数，这个函数返回三种状态，成功 失败 完成。

3.前后端配合规范

3.1 文档书写规范

接口文档书写清晰，尽量避免错别字以及语句歧义
如有特殊情况，对应接口后面加以备注