前端开发规范

一棵树～

于 2021-05-25 17:14:52 发布

阅读量275

点赞数

分类专栏：【开发规范】

本文链接：https://blog.csdn.net/MyronCham/article/details/117260339

版权

【开发规范】专栏收录该内容

9 篇文章 5 订阅

订阅专栏

一、概述

如何提高代码的审美能力，让代码看上去非常的简洁统一？

好的代码应该 “看上去养眼”，好的代码缩进、对齐、顺序，能代码变得更易读

多人协作，统一的代码风格、良好的结构、明了的注释，能提升协同开发效率，降低维护成本

基本原则

使用一致的布局
把相关代码行分组，形成代码块，重构、拆分
让相同的代码，抽离出来组成公用组件

文档手册

二、项目规范

项目命名

全部采用 小写 方式，以中划线 - 分隔

正例： mall-management-system

反例： mall_management-system、 mallManagementSystem

目录命名

全部采用 小写 方式，以中划线 - 分隔
有复数结构时，要采用 复数命名法 ， 缩写不用复数

正例： scripts 、styles 、user-center 、img 、doc

反例： script 、style 、user_center 、userCenter 、imgs 、docs

README.md 文件

良好的 README 对于项目的交接和维护很重要，它能帮助开发者直观地了解项目的目的、运行方式、采用技术等

一般的，README 应包含一下内容：

项目简介
1. 标题：一个标题应该很清晰地表达这是一个什么项目
2. 介绍：介绍应该短小精悍，2、3句话就可以讲明白这个项目的目的以及解决的问题
3. 技术栈：采用的技术框架、UI 组件库、依赖的主要函数库、处理器、构建打包工具等
4. 线上预览地址
5. 仓库地址
6. 使用文档、接口文档地址
项目成员
参与项目立项、设计、开发、测试、运维的相关人员的基本信息，便于及时找到对接负责人
1. 主负责人
2. 开发者
3. 测试
4. 运维
5. UE设计
6. UI设计
安装和运行
这部分很重要，应简明的描述清楚项目的运行环境要求、安装方式、开发启动、发布、测试、代理设置等信息
1. 运行环境
2. 分支说明
3. 安装
4. 开发
5. 发布
6. 测试
7. 格式化
8. 代理设置
项目目录

目录提供了一个各部分内容的快捷入口，说明主要文件的层级结构
功能特性
简要介绍项目已开发完成各个模块的功能和路由信息
1. 功能说明（规划中、开发中、测试中、已完成、暂停、已废弃）
2. 路由信息
3. 存在的问题
项目状态

项目处于 开发阶段 还是 测试阶段 或者 已经完成 ，是 停止维护 还是 迁移到新项目
版本记录

版本迭代过程中，主体依赖的变化，功能模块的变化，bug修复记录等
文档和来源

开发、迭代、优化过程中，查阅的文档、教程、博客，或从技术论坛查询的解决方案，写下关键信息或链接

参考的开源项目的链接和版本

文件命名

HTML：.html、.htm
CSS：.css、.less、.scss、.styl(Stylus)
JS：.js、.jsx、.ts、.tsx、.vue
Image：.jpg、.jpeg、.png、.gif、.webp、.svg
全部采用 小写 方式，以中划线 - 分隔

正例： index.html、base.css、user-center.js、user-icon.png

反例： user_center.js、userCenter.js

通用目录结构

├── node_modules 依赖包 ├── public 模板html、ico ├── src │ ├── api 接口请求处理统一文件 │ │ ├── request.js 基于 axios 封装请求模块 │ │ ├── index.js 对应的页面接口api │ ├── assets 静态资源文件夹 │ │ ├── images 图片 │ │ ├── styles css 全局css sass/less变量 │ ├── components 可复用全局组件 │ ├── router 项目路由 │ ├── store 状态管理 │ │ ├── index.js 状态管理入口文件 │ │ ├── modules 状态模块文件夹 │ ├── utils 常用全局方法文件夹 │ │ ├── const 存放常量文件夹：正则、其它变量 │ ├── pages 页面文件夹 │ │ ├── index 页面模块文件夹 │ │ ├── const.js 每个页面的常量配置，如表格的搜索条 │ │ ├── Index.vue 对应的页面使用大写驼峰命名或者小写中划线命名name-name.vue │ ├── App.js │ ├── main.js 页面入口文件 ├── package.json 描述应用的依赖关系和对外暴露的脚本接口 ├── webpack.config.js 项目webpack配置

三、HTML 规范

HTML 类型

使用 HTML5 的文档类型申明：

建议使用 text/html 格式的 HTML
避免使用 XHTML（XHTML 以及它的属性，比如 application/xhtml+xml 在浏览器中的应用支持与优化空间都十分有限）

doctype 大写
给 html 标签上加上 lang 属性，利于翻译工具
规定字符编码 UTF-8
IE 兼容模式，优先使用高版本IE、谷歌浏览器
移动设备添加 viewport
引入资源使用相对路径，不要指定资源所带的具体协议 ( http:,https: )
css放头部，js文件放底部
给 <a> 标签加上title属性

<!DOCTYPE html>  <html lang="zh-cn">  <head> <meta charset="UTF-8" />  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />  <meta name="viewport" content="initial-scale=1, maximum-scale=3, minimum-scale=1, user-scalable=no" />  <title>HTML 类型</title> <link rel="stylesheet" href="./styles/base.css">  </head> <body> <h2>凌久-前端规范</h2> </body> <script src="//libs.baidu.com/jquery/2.0.0/jquery.min.js"></script>  </html>

语义化标签

HTML5 中新增很多语义化标签，所以优先使用语义化标签，避免一个页面都是 div 或者 p 标签

<header>定义头部</header> <footer>定义底部</footer> <main>定义主体</main> <template>模板标签</template> <section>定义一个区域</section> <aside>定义侧边栏</aside> <nav>标记定义导航链接</nav> <mark>定义重要或强调的内容</mark> <time>定义日期/时间</time> <progress>定义任务进度</progress> <dialog>定义对话框或窗口</dialog> <article>标记一篇文章</article> <code>定义代码框</code> <figure>定义一组媒体内容及它们的标题</figure> <figcaption>定义 figure 元素的标题</figcaption>

缩进

缩进使用 4 个空格（一个 tab）
嵌套的节点应该缩进

属性和属性值

属性值：用双引号 " " ，而不用单引号
属性顺序：
```
 
```
id class name data-xxx src, for, type, href title, alt aria-xxx, role

四、CSS 规范

命名

ID 和 class 的名称总是使用可以反应元素目的和用途的名称，或其他通用的名称，代替表象和晦涩难懂的名称

id 采用驼峰式命名，且一个文件里，id 唯一
类名使用小写字母，以中划线分隔
scss 中的变量、函数、混合、placeholder 采用驼峰式命名

选择器和属性

避免使用ID选择器及全局标签选择器防止污染全局样式
组件化、模块化的开发过程中，合理使用css命名空间
```
 
```
  <div class="index"> <header class="header"></header> <footer class="footer"></footer> <div> <style lang="scss"> .index{ .header{} .footer{} } </style>
css 选择器中避免使用标签名

浏览器解选择器时规则是 right-to-left，使用标签选择器，会带来性能问题
选择器嵌套，尽量3层以内，最多4层
推荐使用 子选择器，而不是 后代选择器
```
 
```
/*不推荐*/ .content > .title { font-size: 16px; } /*推荐*/ .content .title { font-size: 16px; }
每个选择器及属性独占一行
尽量使用缩写属性，遵循：上右下左的顺序
```
 
```
/*不推荐*/ padding-top: 0; padding-right: 12px; padding-bottom: 10px; padding-left: 12px; /*推荐*/ padding: 0 12px 10px;
省略0后面的单位
在 -1 和 1 之间时去掉小数点前的 0，直接用 .5px
px: 浏览器默认最小像素为12px

五、图片

使用恰当的图片格式

jpg：内容图片为照片之类的
png：装饰图片，通常更适合用无损压缩
gif：基本上除了 gif 动画外不要使用
webP：大大减小图片的体积，但是移动端有兼容性问题

雪碧图

CSS Sprites ，是一种 CSS 图像合成技术，主要用于小图片显示

把诸多小图片合成一张大图，利用backround-position属性值来确定图片呈现的位置，这样就能减少 http 请求，到达性能优化的效果

iconfont

字体图标，即通过字体的方式展示图标，多用于渲染图标、简单图形、特殊字体等

只需要引入对应的字体文件即可，这种方法可有效减少 HTTP 请求次数，而且一般字体体积较小，所以请求传输数据量较少。与直接引入图片不同，iconfont 可以像使用字体一样，设置大小、颜色及其他样式，且不存在失真的情况

图片懒加载

暂时不设置图片的 src 属性，而是将图片的 url 隐藏起来，比如先写在 data-src 里面，等某些事件触发的时候(比如滚动到底部，点击加载图片)再将图片真实的 url 放进 src 属性里面，从而实现图片的延迟加载

六、JS 规范

整体风格

统一使用 ES6+ 语法
变量申明：let ，常量申明： const ，禁用 var
句末省略分号 ;

命名

命名 语义化 ，看到名称就能明白含义，禁用英语缩写，禁用汉语拼音
变量名、参数名、函数名：统一使用 lowerCamelCase 风格
常量名：全部大写，多个单词用下划线 _ 拼接
复数时，在命名上体现出来

字符串

统一使用 单引号，而不是双引号
用 字符串模板 而不是 + 来拼接字符串

数组

创建数组用 字面量 方式，禁用 new Array
尽量使用 数组解构 来取值
数组浅拷贝用 扩展运算符 ，即：[...array]
类数组对象转成数组用 Array.from(arrLike)

对象

创建对象用 字面量 方式，禁用 new Object
尽量使用 对象解构 来取值
对象浅拷贝时，更推荐使用扩展运算符 ...，而不是 Object.assign

函数

函数名，必须是 动词 + 名词 形式
尽量使用箭头函数
构造函数，用 class 替代
函数参数使用 默认值 ，替代函数体内部的条件语句进行赋值，且默认参数赋值放在最后
函数参数越少越好，如果参数超过两个，使用 解构语法 ，不用考虑参数的顺序
优先使用 rest 语法 ... ，而不是 arguments
增、删、改、查、详情，分别使用：add、 delete、 update、 query、 detail 做动词
函数方法常用动词组
```
 
```
get 获取， set 设置 add 增加， remove 删除 insert 插入， delete 移除 create 创建， destory 销毁 start 启动， stop 停止 open 打开， close 关闭, read 读取， write 写入 load 载入， save 保存, create 创建， destroy 销毁 begin 开始， end 结束, backup 备份， restore 恢复 import 导入， export 导出, split 分割， merge 合并 inject 注入， extract 提取, attach 附着， detach 脱离 bind 绑定， separate 分离, view 查看， browse 浏览 edit 编辑， modify 修改, select 选取， mark 标记 copy 复制， paste 粘贴, undo 撤销， redo 重做 add 加入， append 添加 clean 清理， clear 清除, index 索引， sort 排序 find 查找， search 搜索, increase 增加， decrease 减少 play 播放， pause 暂停, launch 启动， run 运行 compile 编译， execute 执行, debug 调试， trace 跟踪 observe 观察， listen 监听, build 构建， publish 发布 input 输入， output 输出, encode 编码， decode 解码 encrypt 加密， decrypt 解密, compress 压缩， decompress 解压缩 pack 打包， unpack 解包, parse 解析， emit 生成 connect 连接， disconnect 断开, send 发送， receive 接收 download 下载， upload 上传, refresh 刷新， synchronize 同步 update 更新， revert 复原, lock 锁定， unlock 解锁 check out 签出， check in 签入, submit 提交， commit 交付 push 推， pull 拉, expand 展开， collapse 折叠 begin 起始， end 结束, start 开始， finish 完成 enter 进入， exit 退出, abort 放弃， quit 离开 obsolete 废弃， depreciate 废旧, collect 收集， aggregate 聚集

模块

在非标准模块系统上使用(import/export)
```
 
```
// 不推荐 const AirbnbStyleGuide = require('./AirbnbStyleGuide') module.exports = AirbnbStyleGuide.es6 // 凑合 import AirbnbStyleGuide from './AirbnbStyleGuide' export default AirbnbStyleGuide.es6 // 推荐 import { es6 } from './AirbnbStyleGuide' export default es6
一个入口只 import 一次
```
 
```
// 不推荐 import foo from 'foo' import { named1, named2 } from 'foo' // 推荐 import foo, { named1, named2 } from 'foo
只有一个导出的模块里，用 export default
```
 
```
// 不推荐 export function foo() {} // 推荐 export default function foo() {}

注释

文件注释
```
 
```
/** * @author Well * @date 2021-05-06 * @description 用户账号模块接口文件 */
公共方法注释
```
 
```
/** * @author Well * @date 2021-05-06 * @description 获取用户信息 * @param type {number} * @return {object} 包含用户信息的对象 */ function getUserInfo(type = 0) { if(type === 0) { // todo return {} } if(type === 1) { // todo return {} } }
私有方法注释
```
 
```
/** * @description 获取用户信息 * @param type {number} * @return {object} 包含用户信息的对象 */ function getUserInfo(type = 0) { if(type === 0) { // todo return {} } if(type === 1) { // todo return {} } }
单行注释：// 后跟一个空格，缩进与下一行被注释说明的代码一致
多行注释：使用 /*...*/

杂项

for 循环：用一个变量来接收数组的长度，能提高代码执行效率，而不是一次循环，都得重新计算数组长度
```
 
```
// 不推荐 for(let i = 0; i < arr.length; i++) {} // 推荐 for(let i = 0, len = arr.length; i < len; i++) {}
定时器：setTimeout 和 setInterval 要及时清理（clearTimeout 和 clearInterval），已节省开销
多 if 判断：建议用 if + return
this 的转换命名：上下文 this 的引用只能使用 self 来命名