前端项目相关规范
为什么要规范项目?
- 阅读体验差
接手过别人代码的人都深有体会,有的代码动不动 3-5 千行,有的 aa,bb,,cc 的变量命名,还有 a1,a2,a3 的命名,还有换行、空格各种各样的,甚至不换行、不空格的。哎,说多了都是泪,所以这严重影响工作效率和团队协作。简单来说,太过随意的代码会让强迫症患者难以容忍,难以阅读理解的代码有时甚至不如推倒重来。
- 低质量的代码产生 BUG
墨菲定律已经深入人心,就不需要我解释了吧,代码看着就有问题,那么肯定会出问题的。不换行,没有 lint 工具的开发者,一个 html 标签没有闭合都没法检测出来,那肯定会出现问题啊。
- 功能不分离,逻辑糅合,难以阅读和理解
这种问题其实是非常普遍的。一个函数几百行、一个文件数千行、一个类几十个方法、方法参数定义随意、没有任何注释、方法与变量命名无明确的语义、数据修改与变更穿插在各种方法中等等。
lint 工具
使用 eslint 校验 js 语法, prettier 代码格式化
eslint
ESLint 是一个插件化的 javascript 代码检测工具,它可以用于检查常见的 JavaScript 代码错误,也可以进行代码风格检查,这样我们就可以根据自己的喜好指定一套 ESLint 配置,然后应用到所编写的项目上,从而实现辅助编码规范的执行,有效控制项目代码的质量。
- 选择你想要的模式,生成配置文件.eslintrc.js 内容如下。
module.exports = {
env: {
browser: true,
es6: true
},
extends: "eslint:recommended",
rules: {
// 'no-console': 'off' 表示可以用console打印信息
"no-console": "off",
// 'semi'项设置可不用;作为代码行结束
semi: ["error", "never"]
}
};
js 语法非常灵活,像;
结尾符在别的语言中都是必须的,但是在 js 中是非必须的,只要换行就可不适用;
封闭符,但是这样很不规范
prettier
Prettier 的中文意思是“漂亮的、机灵的”,也是一个流行的代码格式化工具的名称,它能够解析代码,使用你自己设定的规则来重新打印出格式规范的代码。
- 和 eslint 一起使用,可以校验代码的格式问题:
yarn add --dev prettier eslint-plugin-prettier
// .eslintrc.json
{
"plugins": ["prettier"],
"rules": {
"prettier/prettier": "error"
}
}
- 关闭 ESLint 的格式规则
你特别不想要 ESLint 仅仅是和 Prettier 有简单的不同和偏好而报出“问题”,想只采用 prettier 来格式化的话
yarn add --dev eslint-config-prettier
// .eslintrc.json
{
"extends": ["prettier"]
}
其实一般会不将他们一起使用,因为还是有些许不同之处,我们一般使用 eslint 的精确校验 js,es6,ts 的语法问题,使用 prttier 的格式化代码功能。
编辑器工具
vscode (推荐-微软出品,轻量,插件市场丰富,完全支持微软的 ts 的校验)
Vscode 是一个轻量的编译器,所以默认是通过打开文件夹的功能来打开对应的工程
- 一个 tab 占多少个空格问题
统一使用 1 个 tab 占 2 个空格
"editor.tabSize": 2,
- 保存时自动格式化代码
"editor.formatOnSave": true,
"eslint.autoFixOnSave": true,
- 一行最大字符长度
"editor.wordWrapColumn": 50,
"editor.wordWrap": "on"
webstorm
WebStorm 是 jetbrains 公司旗下一款 JavaScript 开发工具。目前已经被广大中国 JS 开发者誉为“Web 前端开发神器”、“最强大的 HTML5 编辑器”、“最智能的 JavaScript IDE”等。
sublime text3
Sublime Text 是一个代码编辑器。也是 HTML 和散文先进的文本编辑器。Sublime Text 3 漂亮的用户界面和非凡的功能,例如:迷你地图,多选择,Python 插件,代码段等等。完全可自定义键绑定,菜单和工具栏等等.漂亮的用户界面和非凡的功能,Sublime Text 的主要功能包括:拼写检查,书签,完整的 Python API , Goto 功能,即时项目切换,多选择,多窗口等等。
语法相关
html 语法
- 使用 HTML5 的文档声明类型 :
DOCTYPE 标签是一种标准通用标记语言的文档类型声明,它的目的是要告诉标准通用标记语言解析器,它应该使用什么样的文档类型定义(DTD)来解析文档。使用文档声明类型的作用是为了防止开启浏览器的怪异模式。如果你的页面添加了<!DOCTYP>那么,那么就等同于开启了标准模式。浏览器会按照 W3C 标准解析渲染页面。
-
使用 UTF-8 的字符集
-
使用语义化标签,如 header, footer 等
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="X-UA-Compatible" content="ie=edge" />
<title>Document</title>
</head>
<body>
<header>头部</header>
<footer>脚部</footer>
</body>
</html>
- 脚本加载
说到 js 和 css 的位置,大家应该都知道 js 放在下面,css 放在上面。但是,如果你的项目只需要兼容 ie10+或者只是在移动端访问,那么可以使用 HTML5 的新属性 async,将脚本文件放在内
- alt 标签不为空
标签的 alt 属性指定了替代文本,用于在图像无法显示或者用户禁用图像显示时,代替图像显示在浏览器中的内容。
- 如要考虑兼容性,需遵循 w3c 标准
css 语法规范相关
- 合理的使用 ID
一般情况下 ID 不应该被用于样式,并且 ID 的权重很高,所以不使用 ID 解决样式的问题,而是使用 class
- 类名命名
使用-分割,且语义化命名,如下示范
/* 错误示范 */
.aaBB {
font-size: 20px;
}
/* 正确示范 */
.header-title {
font-size: 20px;
}
- 0 与 ‘0px’ 时选择 0
{
/* 正确 */
margin: 0;
}
{
/* 错误 */
margin: 0px;
}
- 书写时换行
<!-- 错误 -->
{text-align: center; text-overflow: ellipsis;}
/* 正确 */
{
text-align: center;
text-overflow: ellipsis;
}
- 能用 css 实现不使用 js 来实现
js 语法相关
命名
- 帕斯卡命名法
Pascal Case 大驼峰式命名法:首字母大写。eg:StudentInfo、UserInfo、ProductInfo
- 驼峰式命名法
Camel Case 小驼峰式命名法:首字母小写。eg:studentInfo、userInfo、productInfo
- 文件资源命名
1. 文件名不得含有空格
2. 文件名建议只使用小写字母,不使用大写字母。
3. 文件名及目录名不得包含中文
- 组件名采用帕斯卡命名法,如:
import CheckCode from "@/components/CheckCode";
- 类,构造函数使用帕斯卡命名法,如:
function Student(name) {
this.name = name;
}
// class
class Student {
constructor(props, name) {
super(props);
this.name = name;
}
}
- 私有属性和方法,如:
function Student(name) {
var _name = name; // 私有成员
}
- 变量、属性名、函数命名要语义化,使用驼峰命名法,如:
let userName = "mySkey";
- 常量名称全部大写,如:
const PI = Math.PI;
- 注释
单行注释: 两斜线开始,代码上方或者代码右方,如:
// 设置title
setTitle();
let maxCount = 10; // 设置最大值
多行注释
/*
* 代码执行到这里后会调用setTitle()函数
* setTitle():设置title的值
*/
函数注释
/**
* 获取用户信息
* @param {string} id 用户id
* @param {[string|number]} type 用户类型
* @param {number} [index] 排名
* return {Array} 返回此id下的数组
*/
function getUserMsg(id, type, index) {
return [];
}
- 文件拆分
超过 500 行的文件可读性就很差了,需要对其进行功能或业务或结构层面的拆分,然后使用 es6 的模块化功能
export default Component;
import Component from "./component";
- 代码缩进
通常使用 2 个空格符号来缩进代码块:
function toCelsius(fahrenheit) {
return (5 / 9) * (fahrenheit - 32);
}
- 使用
===
替换所有==
== // equality 等同:两边值类型不同的时候,要先进行类型转换,再比较
=== // identity 恒等:不做类型转换,类型不同的一定不等
- 不要使用 eval()语句
不要使用 eval()语句,因为它存在安全隐患,导致脚本注入攻击,并且在不同的浏览器引擎下还有效率上的差异
- 不要在循环里面进行 DOM 操作
//推荐
var htmlString = "";
for(var i =0; i<length;i++){
htmlString += html;
}
$(“.class”).append(htmlString);
//不推荐
for(var i =0; i<length;i++){
$(“.class”).append(html);
}
技术栈选择
所有的一切都是以 html、css、javascript 为基石
- css 预处理器
使用 less,less 基本具备 sass 的全部特性,但是比 sass 轻量更多,推荐项目中使用 less
- pc 端项目及后台管理系统
使用 umi + yarn + typescript + antd,react 项目使用 yarn 作为包管理工具,大型项目中使用 typescript 作为静态类型检测,强类型检测能保证团队的协作,也为后期的维护减少成本,所以在 pc 和后台管理系统中使用 typescript 很有必要,而且大型项目中,react 的性能会超 vue,react 也对 ts 更友好,所以采用这套技术
mkdir umi-project && cd umi-project
$ yarn create umi
- 移动端项目
使用 vue-cli3 + npm + vue + vant-ui,vue 具有轻捷、快速的特性,能快速创建项目,搭建环境,并且最终的打包大小很有优势,移动端网络情况很不稳定,需要在打包大小上做严格的限制。
vue create hello-world
- 图表库
使用 echarts
- 地图
使用高德地图
- 打包工具
使用 webpack
- 代码管理
使用 git,并且重大改动或者不确定会保留不的改动重新建分支
- 调试工具
// 微信端
使用微信开发者工具调试;
// pc 与 移动端
使用google的chrome调试;
// native
使用真机调试;
PC 项目相关
- 语法遵循 eslint 规范
使用 eslint 和 prettier 格式化文件
- 使用 typescript
利用好 interface,将项目变得可管理起来
- 接口配置
接口的 baseUrl 根据环境读取,单独页面的接口配置抽离到单独目录进行管理
- 复用性组件和模块必须抽离
在 components 和 utils 目录下分别放公用的组件和模块,并且组件和模块必须要有明确的 interface,不然在使用时一样不方便,有注释就更好了
- 代码抽离
超出 500 行的代码可读性很差
- 不能调整三方依赖的版本超过一个大版本
三方依赖超出一个大版本导致无法兼容,可能导致无法预期的问题
移动端项目
- 使用相对单位 rem 适配,定义 1rem = 10px
html {
font-size: 2.666666vw;
}
- 对打包完的大小要严格控制
网页遵循 258 原则,网站在 2s 内打开,用户体验很好,在 5s 内打开,用户还可以接受,要是超出 8s,基本上没有人会认为这个是正常的,基本不会等你了。移动端项目多是 C 端项目,用户网络、机型等复杂性很有可能会网卡,所以对他们需要加载的内容越轻越好(当然要实现功能)
- 对图片使用懒加载
移动端加载资源都是很耗费时间的,所以图片懒加载很有必要
- 路由、组件异步加载
组件与路由使用异步加载,保证用户体验
- 在未使用打包工具的时候,慎用新特性
平时的项目使用 webpack 打包压缩,webpack 内置了 babel 将高级语法编译成 javascript 语法,如果未使用打包工具,移动端项目存在直接 html、css、js 的项目,那么避免使用 css3 的、es6 的新特性,否则会出现不可预期的结果
- 代码抽离
超出 500 行的代码可读性很差
Native 项目
-
遵循相关native技术的编程规范
-
代码抽离
超出 500 行的代码可读性很差