前端代码开发规范指南

前端代码开发规范指南

目录

概述

关于

该前端代码开发规范是参考目前主流的前端团队的前端代码开发规范文档整理，并结合目前团队的业务与开发总结而制定，旨在增强团队的协作，高效开发，提高代码质量。

以下会在HTML规范、CSS规范、JavaScript规范、Vue规范等方面进行规范约定描述。

HTML规范

语法

  • 缩进使用4个空格；
  • 嵌套的节点应该缩进；
  • 在属性上，使用双引号，不要使用单引号；
  • 属性名全小写，用中划线做分隔符；
  • 不要在自动闭合标签结尾处使用斜线；
<!DOCTYPE html>
<html>
  <head>
      <meta charset="utf-8">
      <title>Page title</title>
  </head>
  <body>
      <img src="images/company_logo.png" alt="Company">
      <h1 data-hiddern="false">Hello world!</h1>
  </body>
</html>

DOCTYPE 声明

在页面开头使用doctype来启用标准模式，使其在每一个浏览器中尽可能一致地展示； 虽然doctype不区分大小写，但按照惯例，doctype使用大写。

<!DOCTYPE html>
<html>
   ...
</html>

页面语言lang

考虑浏览器和操作系统的兼容性，推荐使用属性值 zh-CN

<!DOCTYPE html>
<html lang="zh-CN">
    ...
</html>

字符编码

通过声明一个明确的字符编码，让浏览器轻松、快速的确定适合网页内容的渲染方式，通常指定为'utf-8'。

<!DOCTYPE html>
<html>
  <head>
      <meta charset="utf-8">
  </head>
  ...
</html>

浏览器渲染模式

用 <meta> 标签可以指定页面应该用什么版本来渲染； 建议使用优先使用 IE 最新版本和 Chrome Frame;

<!DOCTYPE html>
<html>
  <head>
      <!-- 优先使用 IE 最新版本和 Chrome Frame -->
      <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"/>
  </head>
  ...
</html>

类型属性

根据HTML5规范, 通常在引入CSS和JS时不需要指明 type，因为 text/css 和text/javascript 分别是他们的默认值。

<!-- 引入CSS样式 -->
<link rel="stylesheet" href="code_guide.css">

<!-- 内嵌CSS样式 -->
<style>
    ...
</style>

<!-- 引入JS脚本 -->
<script src="code_guide.js"></script>

<!-- 内嵌JS脚本 -->
<script>
    ...
</script>

属性顺序

属性应该按照特定的顺序出现以保证易读性；

  • class
  • id
  • name
  • data-*
  • src, for, type, href, value , max-length, max, min, pattern
  • placeholder, title, alt
  • aria-*, role
  • required, readonly, disabled

class是为高可复用组件设计的，所以应处在第一位； id更加具体且应该尽量少使用，所以将它放在第二位。

代码嵌套

在编写HTML代码时，需要尽量避免多余的父节点，元素嵌套规范，每个块状元素独立一行，内联元素可选,

推荐：

<img class="avatar" src="...">
<div>
    <h1></h1>
    <p></p>
</di>
<p><span></span><span></span></p>

不推荐：

<span class="avatar">
    <img src="...">
</span>

<div>
    <h1></h1><p></p>
</di>
<p>
    <span></span>
    <span></span>
</p>

特殊字符引用

在 HTML 中不能使用小于号 “<” 和大于号 “>”特殊字符，浏览器会将它们作为标签解析，若要正确显示，在 HTML 源代码中使用字符实体

推荐：

<!-- 推荐 -->
<a href="#">more&gt;&gt;</a>

不推荐：

<a href="#">more>></a>

注释

单行注释

一般用于简单的描述，如某些状态描述、属性描述等

注释内容前后各一个空格字符，注释位于要注释代码的上面，单独占一行

推荐：

<!-- Comment Text -->
<div>...</div>

不推荐：

<div>...</div><!-- Comment Text -->

<div><!-- Comment Text -->
    ...
</div>

模块注释

一般用于描述模块的名称以及模块开始与结束的位置

注释内容前后各一个空格字符，<!-- S Comment Text --> 表示模块开始，<!-- E Comment Text --> 表示模块结束，模块与模块之间相隔一行

推荐：

<!-- S Comment Text A -->
<div class="mod_a">
    ...
</div>
<!-- E Comment Text A -->

<!-- S Comment Text B -->
<div class="mod_b">
    ...
</div>
<!-- E Comment Text B -->

不推荐：

<!-- S Comment Text A -->
<div class="mod_a">
    ...
</div>
<!-- E Comment Text A -->
<!-- S Comment Text B -->
<div class="mod_b">
    ...
</div>
<!-- E Comment Text B -->

嵌套模块注释

当模块注释内再出现模块注释的时候，为了突出主要模块，嵌套模块不再使用

<!-- S Comment Text -->
<!-- E Comment Text -->

而改用

<!-- /Comment Text -->

注释写在模块结尾标签底部，单独一行。

<!-- S Comment Text A -->
<div class="mod_a">

    <div class="mod_b">
      ...
    </div>
    <!-- /mod_b -->

    <div class="mod_c">
      ...
    </div>
    <!-- /mod_c -->

</div>
<!-- E Comment Text A -->

CSS规范

语法

  • 缩进使用4个空格；
  • 代码格式化开发使用展开式书写样式，生产环境使用紧凑格式；
  • 样式选择器，属性名，属性值关键字全部使用小写字母书写，属性字符串允许使用大小写；
  • 每个属性声明末尾都要加分号；

样式编码

  • 样式文件必须写上 @charset 规则，并且一定要在样式文件的第一行首个字符位置开始写，编码名用 “UTF-8”
  • 字符 @charset “”; 都用小写字母，不能出现转义符，编码名允许大小混写

推荐：

@charset "UTF-8";
.header{}

不推荐：

/**
 * @desc File Info
 * @author Author Name
 * @date 2018-01-28
 */

/* @charset规则不在文件首行首个字符开始 */
@charset "UTF-8";

.header{}


@CHARSET "UTF-8";
/* @charset规则没有用小写 */
.header{}

/* 无@charset规则 */
.header{}

属性书写顺序

建议遵循以下顺序：

  1. 布局定位属性：display / position / float / clear / visibility / overflow
  2. 自身属性：width / height / margin / padding / border / background
  3. 文本属性：color / font / text-decoration / text-align / vertical-align / white- space / break-word
  4. 其他属性（CSS3）：content / cursor / border-radius / box-shadow / text-shadow / background:linear-gradient …
.header{
    display: block;
    position: relative;
    float: left;
    width: 100px;
    height: 100px;
    margin: 0 10px;
    padding: 20px 0;
    font-family: Arial, 'Helvetica Neue', Helvetica, sans-serif;
    color: #333;
    background: rgba(0,0,0,.5);
    -webkit-border-radius: 10px;
    -moz-border-radius: 10px;
    -o-border-radius: 10px;
    -ms-border-radius: 10px;
    border-radius: 10px;
}

CSS3浏览器私有前缀写法

CSS3 浏览器私有前缀在前，标准前缀在后

.header{
    -webkit-border-radius: 10px;
    -moz-border-radius: 10px;
    -o-border-radius: 10px;
    -ms-border-radius: 10px;
    border-radius: 10px;
}

选择器

  • 尽量少用通用选择器 *
  • 合理的使用ID,尽量少使用 ID 选择器
  • 尽量少使用无具体语义定义的标签选择器

推荐

.header {}
.header li {}
.header li p{}

不推荐

*{}
#header {}
.header div{}

0后面不带单位

省略0后面的单位，

推荐

.header {
  padding-bottom: 0;
  margin: 0;
}

不推荐

.header {
  padding-bottom: 0px;
  margin: 0em;
}

ClassName命名

ClassName的命名应该尽量精短、明确，必须以字母开头命名，且全部字母为小写，单词之间统一使用下划线 “_” 连接

命名原则 :基于姓氏命名法（继承 + 外来），如下图：

前端代码开发规范指南

祖先模块不能出现下划线:

推荐：

<div class="modulename">
    <div class="modulename_info">
        <div class="modulename_son"></div>
        <div class="modulename_son"></div>
        ...
    </div>
</div>

不推荐：

<div class="modulename_info">
    <div class="modulename_info_son"></div>
    <div class="modulename_info_son"></div>
    ...
</div>

在子孙模块数量可预测的情况下，严格继承祖先模块的命名前缀

<div class="modulename">
    <div class="modulename_cover"></div>
    <div class="modulename_info"></div>
</div>

当子孙模块超过4级或以上的时候，可以考虑在祖先模块内具有识辨性的独立缩写作为新的子孙模块

推荐：

<div class="modulename">
    <div class="modulename_cover"></div>
    <div class="modulename_info">
        <div class="modulename_info_user">
            <div class="modulename_info_user_img">
                <img src="" alt="">
                <!-- 这个时候 miui 为 modulename_info_user_img 首字母缩写-->
                <div class="miui_tit"></div>
                <div class="miui_txt"></div>
                ...
            </div>
        </div>
        <div class="modulename_info_list"></div>
    </div>
</div>

不推荐：

<div class="modulename">
    <div class="modulename_cover"></div>
    <div class="modulename_info">
        <div class="modulename_info_user">
            <div class="modulename_info_user_img">
                <img src="" alt="">
                <div class="modulename_info_user_img_tit"></div>
                <div class="modulename_info_user_img_txt"></div>
                ...
            </div>
        </div>
        <div class="modulename_info_list"></div>
    </div>
</div>

JavaScript规范

大括号风格

在编程过程中，大括号风格与缩进风格紧密联系，用来描述大括号相对代码块位置的方法有很多。在 JavaScript 中，主要有三种风格，如下：

  • One True Brace Style
if (foo) {
  bar()
} else {
  baz()
}
  • Stroustrup
if (foo) {
  bar()
}
else {
  baz()
}
  • Allman
if (foo)
{
  bar()
}
else
{
  baz()
}

约定使用 One True Brace Style 风格

变量命名

当命名变量时，主流分为驼峰式命名（variableName）和下划线命名（variable_name）两大阵营。

约定使用驼峰式命名

拖尾换行

在非空文件中，存在拖尾换行是一个常见的 UNIX 风格，它的好处是可以方便在串联和追加文件时不会打断 Shell 的提示。在日常的项目中，保留拖尾换行的好处是，可以减少版本控制时的代码冲突。

不推荐

function func () {
  // do something
}

推荐

function func () {
  // do something
}
  // 此处是新的一行

缩进

代码保持一致的缩进，约定使用 空格 来缩进，而且缩进使用两个空格

对象字面量的键值缩进

约定对象字面量的键和值之间不能存在空格，且要求对象字面量的冒号和值之间存在一个空格

不推荐

var obj = { 'foo' : 'haha' }

推荐

var obj = { 'foo': 'haha' }

构造函数首字母大写

在 JavaScript 中 new 操作符用来创建某个特定类型的对象的一个实例，该类型的对象是由一个构造函数表示的。由于构造函数只是常规函数，唯一区别是使用 new 来调用。所以我们团队约定构造函数的首字母要大小，以此来区分构造函数和普通函数。

不推荐

var fooItem = new foo()

推荐

var fooItem = new Foo()

链式调用

链式调用如果放在同一行，往往会造成代码的可读性差，但有些时候，短的链式调用并不会影响美观。所以本规范约定一行最多只能有四个链式调用，超过就要求换行。

链式赋值

链式赋值容易造成代码的可读性差，约定禁止使用链式赋值

不推荐

var a = b = c = 1

推荐

var a = 1
var b = 1
var c = 1

变量声明

JavaScript 允许在一个声明中，声明多个变量。团队约定在声明变量时，一个声明只能有一个变量

不推荐

var a, b, c

推荐

var a
var b
var c

分号

在很多情况下，JavaScript 引擎可以确定一个分号应该在什么位置然后自动添加它。此特征被称为 自动分号插入 (ASI)。

对于是否应该使用分号，也有许多争论，本规范推荐不使用分号，因为我们认为好的工程师应该知道什么时候该加，什么时候不该加。

相关参考 ：semi

操作符的空格

约定操作符前后都需要添加空格

不推荐

var sum = 1+2

推荐

var sum = 1 + 2

避免全局命名空间污染

防止全局命名空间被污染，我们通常的做法是将代码包裹成一个 IIFE(Immediately-Invoked Function Expression)，创建独立隔绝的定义域。也使得内存在执行完后立即释放。

不推荐

var x = 10,
    y = 100;

console.log(window.x + ' ' + window.y);

推荐

(function(log, w, undefined){
  'use strict';

  var x =  10,
      y =  100;

  log((w.x === undefined) +  '  ' + (w.y === undefined));

}(window.console.log, window));

推荐的IIFE写法:

(function () {
  'use strict';

  // Code goes here

}());

如果你想引用全局变量或者是外层 IIFE 的变量，可以通过下列方式传参：

(function($, w, d){
  'use strict';

  $(function() {

    w.alert(d.querySelectorAll('div').length);

  });

}(jQuery, window, document));

不使用eval()函数

如eval的字面意思来说，恶魔，使用eval()函数会带来安全隐患。 eval()函数的作用是返回任意字符串，当作js代码来处理。

相关文章：

猜你喜欢
相关资源
相似解决方案
热门标签
Java Python linux javascript Mysql C# Docker 算法 前端 SpringBoot Redis Vue spring 设计模式 .net core .net kubernetes c++ 数据库 数据结构 大数据 js 机器学习 微服务 Android Go 程序员 面试 JVM ASP.net core 云原生 人工智能 后端 PHP git CSS golang k8s Nginx Django mybatis 深度学习 多线程 React 架构 devops 爬虫 云计算 Spring Boot LeetCode