web 前端开发规范

web 前端开发规范

web 前端开发规范的意义

• 提高团队的协作能力
• 提高代码的复用利用率
• 可以写出质量更高，效率更好的代码
• 为后期维护提供更好的支持

html，css，js 等资源的命名规则

• html 命名规范
  统一用小写英文字母、数字、和下划线组合，不得包含汉字（转义问题）空格（）和特殊字符（）。
  原则：
  方便理解
  方便查找
• css 命名规范
  一般使用 css 功能的英文小写缩写命名：
  实际模块：
  例如：
  表头的样式文件名为 head.css
  弹出窗口的 css 文件名为 pop.css
  共用模块： common.css
• js 命名规范
  一般使用脚本功能的英文小写缩写命名：
  实际模块：
  例如：
  广告条的 JavaScript 文件名为 ad.js
  弹出窗口的 JavaScript 文件名为 pop.js
  共用模块：
  js 文件名;英文命名，后缀 js，共用 common,js
  外部资源：
  jQuery.min.js
  jquery.date.js

html 书写规范

• 文档类型声明及编码: 统一为 html5 声明类型; 编码统一为书写时利用 IDE 实现层次分明的缩进;
• 非特殊情况下样式文件必须外链至之间;非特殊情况下 JavaScript 文件必须外链至页面底部;
• 引入 JS 库文件, 文件名须包含库名称及版本号及是否为压缩版, 比如jquery-1.7.1.min.js; 引入插件, 文件名格式为库名称+插件名称, 比如jQuery.cookie.js;
• 所有编码均遵循 xhtml 标准, 标签 & 属性 & 属性命名 必须由小写字母及下划线数字组成, 且所有标签必须闭合; 属性值必须用双引号包括;
• 充分利用无兼容性问题的 html 自身标签, 比如span, em, strong, optgroup, label,等等; 需要为html元素添加自定义属性的时候, 首先要考虑下有没有默认的已有的合适标签去设置, 如果没有, 可以使用须以"data-"为前缀来添加自定义属性，避免使用"data:"等其他命名方式;
• 语义化 html, 如 标题根据重要性用 h(同一页面只能有一个 h1), 段落标记用 p, 列表用 ul, 内联元素中不可嵌套块级元素;
• 尽可能减少 div 嵌套
• 书写链接地址时, 必须避免重定向，例如：href="http://www.example.com/", 即须在 URL 地址后面加上"/"；
• 在页面中尽量避免使用 style 属性,即 style=”…”，应该尽量使用 class 或者 id 来定义新的样式，然后再对应的 css 文件里面修改;

js 书写规范

• 文件编码统一为 utf-8, 书写过程过, 每行代码结束必须有分号; 原则上所有功能均根据 XXX 项目需求原生开发, 以避免网上 down 下来的代码造成的代码污染(沉冗代码 || 与现有代码冲突 || …);
• 库引入: 如非必要的库, 需引入第三方库, 须与团队其他人员讨论决定并按需引入;
• 变量命名: 驼峰式命名. 原生 JavaScript 变量要求是纯英文字母, 首字母须小写, 如 car;
• 另要求变量集中声明, 利用闭包避免全局变量.
• 类命名: 首字母大写, 驼峰式命名. 如 Car
• 函数命名: 首字母小写驼峰式命名. 如getCar();
• 命名语义化, 尽可能利用英文单词或其缩写;
• 尽量避免使用存在兼容性及消耗资源的方法或属性, 比如eval() & innerText;
• 后期优化中, JavaScript非注释类中文字符须转换成 unicode 编码使用, 以避免编码错误时乱码显示;
• 代码结构明了, 加适量注释. 提高函数重用率;
• 注重与 html 分离, 减小reflow, 注重性能.
• 注重代码重用性，兼容性，多封装，多面向对象

css 书写规范

• 编码统一为 utf-8;
• 公用文件：协作开发过程中，会引入默认的 base.css(里面包括了 css reset、常用的 css 间距，css 字体，css 大小等，详细参见 base.css)；
• class 与 id 命名: ,样式名称由 小写英文 、 数字 和 _ 来组合命名, 如 i_comment, fontred, width200; 避免使用中文拼音, 尽量使用简易的单词组合；命名要语义化, 简明化。
• 为 JavaScript 预留钩子的命名, 尽量使用 id 属性，可以更快的获取到 dom。
• css 属性书写顺序, 建议遵循: 布局定位属性–>自身属性–>文本属性–>其他属性. 此条可根据自身习惯书写, 但尽量保证同类属性写在一起. 属性列举: 布局定位属性主要包括: display 、 list-style 、 position（相应的 top,right,bottom,left） 、 float & clear 、 visibility 和 overflow； 自身属性主要包括: width 、height 、 margin 、 padding 、 border 和 background; 文本属性主要包括：color 、 font、 text-decoration 、 text-align 、 vertical-align 、 white- space 和其他 content; 我所列出的这些属性只是最常用到的, 并不代表全部;
• 书写代码前, 考虑并提高样式重复使用率;
• 背景图片请尽可能使用 sprite 技术, 减小 http 请求, 考虑到多人协作开发, sprite 按模块制作;
• 必须为大区块样式添加注释, 小区块适量注释;
• 代码缩进与格式: 建议单行书写, 可根据自身习惯, 后期优化会统一处理;

注释规范

• html 注释: 注释格式 , 只能在注释的始末位置,不可置入注释文字区域;
• 包围，请务必要分开注释的文字（即注释文字中加空格）
• css 注释: 注释格式 ;/**/
• JavaScript 注释, 单行注释使用’//这儿是单行注释’ ,多行注释使用 ;/**/
• js 方法注释（包括创建人和时间，变量名和描述）例

/**
 *Created by PanJiaChen on 16/11/29.
 * @param {Sting} url
 * @param {Sting} title
 * @param {Number} w
 * @param {Number} h
 */

• 文件头部注释范例（包括文件描述，作者，时间，最后编辑时间和最后编辑人）

/**
 * @Description: In User Settings Edit
 * @Author: your name
 * @Date: 2019-06-05 16:09:00
 * @LastEditTime: 2019-06-05 16:09:00
 * @LastEditors: your name
 */

非单页面目录及命名规范

• （可根据项目情况增减但需要和组员和组长商量）

├── lib                        # 用来存放第三方库
├── common                     # 用来存放公共文件
│   │── js                     # 公共JavaScript脚本
│   │── css                    # 公共样式
│   └── html                   # 公共html
├── static/src                 # 用来存放静态文件
│   ├── img                    # 用来存放图片资源
│   ├── js                     # 用来存放JavaScript脚本
│   ├── css                    # 样式

vue 单页面应用目录及命名规范

• （可根据项目情况增减但需要和组员和组长商量）

├── build                      # 构建相关
├── mock                       # 项目mock 模拟数据
├── plop-templates             # 基本模板
├── public                     # 静态资源
│   │── favicon.ico            # favicon图标
│   └── index.html             # html模板
├── src                        # 源代码
│   ├── api                    # 所有外层公共请求api
│   ├── assets                 # 主题 字体等静态资源
│   ├── components             # 全局公用组件
│   ├── directive              # 全局指令
│   ├── filters                # 全局 filter
│   ├── icons                  # 项目所有 svg icons
│   ├── lang                   # 国际化 language
│   └──userCenter              # 二级项目名
│      │── api                 # 二级项目api文件夹
|      │── components          # 二级项目公用组件
│      │── views               # 二级项目页面
│      |── assets              # 二级项目资源
│   ├── layout                 # 全局 layout
│   ├── router                 # 路由
│   ├── store                  # 全局 store管理
│   ├── styles                 # 全局样式
│   ├── utils                  # 全局公用方法
│   ├── vendor                 # 公用vendor
│   ├── views                  # views 所有页面
│   ├── App.vue                # 入口页面
│   ├── main.js                # 入口文件 加载组件 初始化等
│   └── permission.js          # 权限管理
├── tests                      # 测试
├── .env.xxx                   # 环境变量配置
├── .eslintrc.js               # eslint 配置项
├── .babelrc                   # babel-loader 配置
├── .travis.yml                # 自动化CI配置
├── vue.config.js              # vue-cli 配置
├── postcss.config.js          # postcss 配置
└── package.json               # package.json

vue 组件规范

• 组件需以业务，以及考虑更高的扩展性为首要
• 组件 props 需要判断参数类型以及需要默认值
• 组件需要对外提供钩子方法和属性以获取组件状态和设置参数等等
• 组件需要尽量适配市面大部分浏览器

eslint 代码检查,git 提交规范和 mock 数据

• 使用mocck 在后台只出文档接口未通的情况下模拟数据开发
• 使用eslint 标准模式规范代码格式
• 使用husky确保eslint检查代码后才能git上传代码
• git 提交代码请写清楚提交备注
• 在合并他人代码解决冲突时如有不确定的情况下需询问相关人员再合并。
• git请自己新建自己的分支，远端只能存在本人的一个开发分支，自己多余的开发分支不要往远端推
• 不要私自切到别人或着master分支去修改提交，除非是本人的分支不要使用rebase合并他人代码，合并生产环境代码，打版本标签需专人去做。