前端规范

2018-09-20  本文已影响0人  泡沫可爱多

前端规范

规范说明

此为前端开发团队遵循和约定的代码书写规范，意在提高代码的规范性和可维护性。
此规范为参考规范，统一团队编码规范和风格。让所有代码都是有规可循的，并且能够得到沉淀，减少重复劳动。

编辑器配置

将编辑器按照下面的配置进行设置，以避免常见的代码不一致和差异；

文件命名

HTML

通用约定

HTML结构大的模块标记开始和结束，方便阅读，新闻类的页面结构遵守SEO标准。

a. 语法
对于属性的定义，确保全部使用双引号，绝不要使用单引号。

b. 引入 CSS 和 JavaScript 文件
根据 HTML5 规范，在引入 CSS 和 JavaScript 文件时一般不需要指定 type 属性，因为 text/css 和 text/javascript 分别是它们的默认值。

c. 标签

<img src="//img.w3cschool.cn/attachments/image/cimg/google.png" alt="Google">
<input type="text" name="title">

<ul>
  <li>Style</li>
  <li>Guide</li>
</ul>

<!-- Not recommended -->
<span class="avatar">
  <img src="...">
</span>

<!-- Recommended -->
<img class="avatar" src="...">

d. Class 与 ID

<!-- Not recommended -->
<div class="j-hook left contentWrapper"></div>

<!-- Recommended -->
<div id="j-hook" class="sidebar content-wrapper"></div>

e. 属性顺序 （不强制遵守）
HTML 属性应该按照特定的顺序出现以保证易读性。

<a id="..." class="..." data-modal="toggle" href="###"></a>

<input class="form-control" type="text">

<img src="..." alt="...">

f. 引号
属性的定义，统一使用双引号。

<!-- Not recommended -->
<span id='j-hook' class=text>Google</span>

<!-- Recommended -->
<span id="j-hook" class="text">Google</span>

g. 嵌套
语义嵌套约束
<li> 用于 <ul> 或<ol> 下；
<dd>，<dt> 用于 <dl> 下；
<thead>，<tbody>，<tfoot>，<tr>，<td> 用于 <table> 下；

h. 布尔值属性
HTML5 规范中 disabled、checked、selected 等属性不用设置值。

<input type="text" disabled>

<input type="checkbox" value="1" checked>

<select>
  <option value="1" selected>1</option>
</select>

语义化

语义化的 HTML 结构，有助于机器（搜索引擎）理解，另一方面多人协作时，能迅速了解开发者意图。
常见标签语义

标签 语义
<p> 段落
<h1> <h2> <h3> ... 标题
<ul> 无序列表
<ol> 有序列表
<b> 为样式加粗而加粗
<storng> 为强调内容而加粗
<i> 为样式倾斜而倾斜
<em> 为强调内容而倾斜
abbr 缩写

例:将构建的页面当作一本书，标签的语义对应的其功能和含义；
书的名称：<h1>
书的每个章节标题：<h2>
章节内的文章标题：<h3>
小标题/副标题：<h4> <h5> <h6>
章节的段落：<p>

HEAD

<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" /><!--优先使用 IE 最新版本和 Chrome-->
    <meta name="renderer" content="webkit">
    <!-- SEO -->
    <title></title>
    <meta name="viewport" content="width=device-width,minimum-scale=1.0,maximum-scale=1.0,user-scalable=0"/><!-- 为移动设备添加 viewport -->
    <meta name="keywords" content="your keywords"><!--页面关键词keywords-->
    <meta name="description" content="description"><!--页面描述内容description-->
    <meta name="author" content="author,email address">
    <meta name="robots" content="index,follow"><!--定义网页搜索引擎索引方式,robotterms是一组使用英文逗号「,」分割的值，通常有如下几种取值：none，noindex，nofollow，all，index和follow-->
    <!-- http cache -->
    <!-- <meta http-equiv="Cache-Control" content="max-age=7200" /> -->
    <meta http-equiv="Cache-Control" content="no-cache" />
    <link rel="shortcut icon" href="path/to/favicon.ico"><!--设置标题小图标-->
    <!-- iOS 图标 (apple-touch-icon-precomposed 禁止系统对图标添加效果)-->
    <link rel="apple-touch-icon" sizes="57x57" href="touch-icon-iphone.png" />  
    <link rel="apple-touch-icon" sizes="72x72" href="touch-icon-ipad.png" />  
    <link rel="apple-touch-icon" sizes="114x114" href="touch-icon-iphone4.png" />    
    <link rel="apple-touch-icon" sizes="144x144" href="apple-touch-icon-ipad3-144.png" />  
    <!--[if lt IE 9]>
    <script src="//cdn.bootcss.com/html5shiv/3.7.3/html5shiv.min.js"></script>
    <script src="//cdn.bootcss.com/respond.js/1.4.2/respond.min.js"></script>
    <![endif]-->
</head>

css

通用约定

a. 代码组织

b. Class 和 ID

c. 引号使用
url() 、属性选择符、属性值使用双引号。

/* Not recommended */
@import url(//www.google.com/css/maia.css);

html {
  font-family: 'Microsoft YaHei', arial, sans-serif;
}

/* Recommended */
@import url("//www.google.com/css/maia.css");

html {
  font-family: "Microsoft YaHei", arial, sans-serif;
}

.selector[type="text"] {

}

d. 空格

/* Not recommended */
.box{
    width:50px;
    height :30px;
    color: rgba(255,255,255,.3);
    transition: width 1s,height 3s;
}

/* Recommended */
.box {
    width: 50px;
    height: 30px;
    transition: width 1s, height 3s;
}

e. 0 值
当属性值为 0 时，省略可省的单位（长度单位如 px、em，不包括时间、角度等如 s、deg）。

/* Not recommended */
margin-top: 0px;

/* Recommended */
margin-top: 0;

f. 媒体查询（Media query）的位置
将媒体查询放在尽可能相关规则的附近。不要将他们打包放在一个单一样式文件中或者放在文档底部。如果分开了，将来只会被遗忘。

.element { ... }
.element-avatar { ... }
.element-selected { ... }

@media (max-width: 768px) {
  .element { ...}
  .element-avatar { ... }
  .element-selected { ... }
}

Less规范

a. 代码组织（按以下顺序组织）

@import "mixins/size.less";

@default-text-color: #333;

.page {
  width: 960px;
  margin: 0 auto;
}

b. @import 语句
@import 语句引用的文需要写在一对引号内，.less 后缀不得省略。引号使用 "" 。

/* Not recommended */
@import "mixins/size";
@import 'mixins/grid.less';

/* Recommended */
@import "mixins/size.less";
@import "mixins/grid.less";

JavaScript

通用约定

a. 语法

b. 注释原则 (单行注释、多行注释)

c. 函数/方法注释

/**
 * 函数描述
 *
 * @param {string} p1 参数1的说明
 * @param {string} p2 参数2的说明，比较长
 *     那就换行了.
 * @param {number=} p3 参数3的说明（可选）
 * @return {Object} 返回值描述
 */
function foo(p1, p2, p3) {
    var p3 = p3 || 10;
    return {
        p1: p1,
        p2: p2,
        p3: p3
    };
}

d. 文件注释
文件注释用于告诉不熟悉这段代码的读者这个文件中包含哪些东西。 应该提供文件的大体内容，依赖关系和兼容性信息。

e. 命名 （不强制遵守）

var loadingModules = {};

var isReady = false;
var hasMoreCommands = false;

var _privateMethod = {};

var HTML_ENTITY = {};

function stringFormat(source) {}

function hear(theBells) {}

function TextNode(value, engine) {
    this.value = value;
    this.engine = engine;
}

TextNode.prototype.clone = function () {
    return this;
};

var TargetState = {
    READING: 1,
    READED: 2,
    APPLIED: 3,
    READY: 4
};

function XMLParser() {}

function insertHTML(element, html) {}

var httpRequest = new HTTPRequest();

组件

以 vue 为例
组件一般情况下是可以拆成基础/ui部分和业务部分，基础组件一般是承载呈现，基础功能，不和业务耦合部分。
业务组件一般包含业务功能业务特殊数据等等。
a. UI组件/基础组件

b. 容器组件

c. 组件通讯

性能优化

尽量避免重定向

减少http请求次数

80%的响应时间在下载网页内容，减少请求次数是缩短响应时间的关键。

文件压缩

异步加载

预加载、延后加载、按需加载

将样式表置顶

将样式表（css）放在网页的 HEAD 中会让网页显得加载速度更快，因为这样做可以使浏览器逐步加载已将下载的网页内容，这对内容比较多的网页尤其重要。除此之外，有些浏览器会在 CSS下载完成后才开始渲染页面，如果 CSS放在靠下的位置则会导致浏览器将渲染时间推迟。

git规范

Commit message

提交信息 类型：内容

类型详细说明见下表格：

类型 用于说明 commit 的类别，只允许使用下面7个标识
feat 新功能（feature）
fix 修补bug
docs 文档（documentation）
style 格式（不影响代码运行的变动）
refactor 重构（即不是新增功能，也不是修改bug的代码变动）
test 增加测试
chore 构建过程或辅助工具的变动

相关参考

前端小团队建设-spademan
为什么文件名要小写？-阮一峰

上一篇 下一篇

猜你喜欢

热点阅读