让前端飞

前端规范

2018-12-10  本文已影响0人  椰果粒

1. 前端开发核心思想

2. 定律

永远遵循同一套代码规范

3. 基本准则

  1. 结构,样式,行为分离
  2. 缩进:统一使用两个空格缩进,不能用tab和空格混搭的样式。
  3. 文件编码:使用不带BOM(Byte order mark)的UTF-8编码。
    • 在文件中指定编码方式:<meta charset="utf-8">
  4. 一律使用小写字母,不能大小写混合。
    1. html示范
      • 正确示范:<img src="a.jpg" alt="dog" title="dog">
      • 错误示范:<IMG src="a.jpg" ALT="dog" title="dog">
    2. css示范
      • 正确示范:color: #e5e5e5;
    • 错误示范:color: #E5E5E5;
  5. 省略外链资源URL协议部分。
    1. 省略外链资源(图片和其他媒体资源)URL中的http/https协议,使URL成为相对地址
    2. 避免mixed content问题,减少文件字节数
    3. 其他协议(ftp等)的URL不省略协议部分
      • html正确示范:<img src="//dog/js/index.js">
      • html错误示范:<img src="http://dog/js/index.js">
      • css正确示范:
        .dog{
            background: url(//www.google.com/images/dog.png);
        }
        
      • css错误示范:
        .dog{
            background: url(http://www.google.com/images/dog.png);
        }
        
  6. 文件命名规范
  1. 注释规范(注释要统一)
    • 可以通过设置编辑器来设置出一致的注释模式。
    1. HTML注释
      • 模块注释
        <!-- 订单详情模块 -->
        
      • 区块注释
        <!-- 
            @name: 订单详情
            @description: 主要是订单详情页面
            @author: fjw(fjw@gmail.com)
        -->
        
    2. CSS注释
      • 组件块和子组件块以及声明块之间使用一空行分隔,子组件块之间三空行分隔;
        /* ==========================================================================
        组件块
        ============================================================================ */
        
        /* 子组件块
        ============================================================================ */
        .selector {
            padding: 15px;
            margin-bottom: 15px;
        }
        
        /* 子组件块
        ============================================================================ */
        .selector-secondary {
            display: block; /* 注释*/
        }
        
        .selector-three {
            display: span;
        }
        
    3. JavaScript注释
      • 单行注释:åå
        • // 独占一行,后跟一个空格,缩进与下一行被注释说明的代码一致。
      • 多行注释:
        • 避免使用 /.../ 这样的多行注释。有多行注释内容时,使用多个单行注释。
      • 函数/方法注释:
        • 必须包含函数的说明;
        • 有参数和返回值时,必须有注释标志;
        • 参数和返回值必须包含类型信息和说明;
        • 当函数是内部函数,外部不可以访问时,可以使用@inner来标识;
        • 示范:
          /**
          * 函数描述
          *
          * @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
              };
          }
          
    4. 文件注释
      • 文件注释用于告诉不熟悉这段代码的读者这个文件中包含哪些东西。
      • 应该提供文件的大体内容, 它的作者, 依赖关系和兼容性信息
      • 示范:
        /**
        * @fileoverview Description of file, its uses and information
        * about its dependencies.
        * @author user@meizu.com (Firstname Lastname)
        * Copyright 2015 Meizu Inc. All Rights Reserved.
        */
        

4. HTML

  1. 标签

    尽量遵循HTML标准和语义,但不要以失去实用性为代价

    • 自闭合标签,无需闭合(img, input, br, hr);
    • 可选闭合标签,需要闭合(</li>, </body>);
    • 尽量减少标签的数量;
  2. class与id的使用

 <!-- 错误示范 -->
 <div class="j-hook left contentWraaper"></div>
 <!-- 正确示范 -->
 <div id="j-hook" class="content-wrapper"></div>
  1. 属性的顺序

    属性应当按照一定的顺序出现,来保证易读性。顺序如下:

    • id
    • class
    • name
    • data-xxx
    • src, for, type, ref
    • title, alt
    • aria-xxx, role
  2. 单双引号

    属性的定义,统一使用双引号。示范如下

    <!-- 正确示范 -->
    <div id="detail" class="red content-wrapper"></div>
    
  3. 嵌套规则

    语义嵌套:浏览器会做容错处理,生成的文档树可能互相不太一样;

    严格嵌套约束:在所有的浏览器都都不被允许;
    1. 语义嵌套约束
    + <li>用于<ul>或者<ol>下
    + <dt><dd>用于<dl>下
    + <thead><tbody><tbody><tr><td>放在<table>下
    2. 严格嵌套约束
    + 行内元素下只能包含文本和行内元素
    + <a>标签里不可以嵌套交互元素,如<a>,<button>,<select>

  4. 布尔值属性

    在HTML中,disabled, selected, checked等属性不用设置值

    <input type="text" disabled>
    <input type="checkbox" value="1" checked>
    <select>
        <option value="1" selected>1</option>
    </select>   
    
  5. 语义化

    • 通常情况下,每个标签都是有语义的,所谓语义就是有各自的功能和含义;
    • 语义化的HTML结构,有助于机器(搜索引擎)理解;
    • 多人协作时,能够快速理解别的开发者的用途;
  6. 脚本引用写在 body 结束标签之前;

  7. 尽量保证结构、表现、行为三者分离,并尽量使三者之间没有太多的交互和联系。尽量在文档和模板中只包含结构性的 HTML;而将所有表现代码,移入样式表中;将所有动作行为,JS脚本之中。

  8. 尽量不使用行内样式;

```
<style>.no-good {}</style>;
```
  1. 在每一个块状元素,列表元素和表格元素后,加上一新空白行,并对其子孙元素进行缩进。内联元素写在一行内,块状元素还有列表和表格要另起一行。

  2. 任何时候都要尽量使用最少的标签并保持最小的复杂度,尽量避免多余的父元素。

  3. 尽量避免通过 JavaScript 生成的标签,它让内容变得不易查找、编辑,并且降低性能。

  4. 重要图片一定要加上alt属性; 给重要的元素和截断的元素加上title;

  5. 标签和含义

    标签 含义
    <p> 段落
    <h1>--<h6> 标题
    <ul> 无序列表
    <ol> 有序列表
    <blockquote> 大段引用
    <cite> 一般小引用
    <b> 为样式加粗
    <strong> 为了强调而加粗
    <i> 为样式倾斜
    <em> 为强调内容而倾斜
    <code> 代码标识
    <abbr> 缩写
  6. 文档类型

    HTML的第一行要加一个标准模式的声明,这样确保了浏览器有一致的表现形式

    <!DOCTYPE html>
    
  7. 语言

    <!-- 中文 -->
    <html lang="zh-Hans">
    
    <!-- 简体中文 -->
    <html lang="zh-cmn-Hans">
    
    <!-- 繁体中文 -->
    <html lang="zh-cmn-Hant">
    
    <!-- English -->
    <html lang="en">
    
  8. 字符编码

    • 应以无BOM的utf-8编码作为文件格式
    • <meta charset="utf-8">必须作为<head>的第一个直接子元素
  9. IE模式兼容

    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
    
  10. SEO优化

    <head>
        <meta charset="utf-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
        <!-- SEO -->
        <title>Style Guide</title>
        <meta name="keywords" content="your keywords">
        <meta name="description" content="your description">
        <meta name="author" content="author,email address">
    </head>
    
  11. viewport

    • viewport:指浏览器窗口内容区的大小,不包括工具条,选项卡等;
    • width:浏览器宽度,输出设备中可见区域宽度;
    • device-width:设备分辨率宽度,输出设备的屏幕可见宽度;
    • initial-scale:初始缩放比例;
    • maximum-scale:最大缩放比例;
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    
  12. favicon

    在未指定 favicon 时,大多数浏览器会请求 Web Server 根目录下的 favicon.ico。为了保证 favicon 可访问,避免 404,必须遵循以下两种方法之一:

    • 在 Web Server 根目录放置 favicon.ico 文件;
    • 使用 link 指定 favicon;
    <link rel="shortcut icon" href="path/to/favicon.ico">
    
  13. 综上,head部分应当这样写:

<!DOCTYPE html>
<html lang="zh-cmn-Hans">
<head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
    <title>Style Guide</title>
    <meta name="description" content="不超过150个字符">
    <meta name="keywords" content="">
    <meta name="author" content="name, email@gmail.com">

    <!-- 为移动设备添加 viewport -->
    <meta name="viewport" content="width=device-width, initial-scale=1.0">

    <!-- iOS 图标 -->
    <link rel="apple-touch-icon-precomposed" href="/apple-touch-icon-57x57-precomposed.png">

    <link rel="alternate" type="application/rss+xml" title="RSS" href="/rss.xml" />
    <link rel="shortcut icon" href="path/to/favicon.ico">
</head>

5. CSS

  1. 代码组织

    • 以组件为单位组织代码段;
    • 制定一致的注释规范;
    • 组件块和子组件块以及声明块之间使用一个空行分割,子组件块之间使用三个空行分割;
    • 如果有多个CSS文件,应当按照组件形式而不是按照页面形式来拆分。因为页面可能会被重组,而组件只会被移动;
  2. 注释

    在写代码之前,要规划好组件的工作方式,局限性和构造他们的方法。具体见基本规则。

  3. class和id

    • 使用语义化、通用的方式命名;
    • 使用连字符命名class和id,不要使用驼峰命名和下划线;
    • 避免嵌套层级太多,最好不要超过3层
    • 避免选择器和class,id叠加使用;

    出于性能考量,在没有必要的情况下避免元素选择器叠加Class、ID 使用。

    元素选择器和ID、Class混合使用也违反关注分离原则。如果 HTML 标签修改了,就要再去修改 CSS 代码,不利于后期维护。

    /* 错误示范 */
    .red {}
    .box_green {}
    .page .header .login #username input {}
    ul#example {}
    
    /* 正确示范 */
    #nav {}
    .box-video {}
    #username input {}
    #example {}
    
  4. 声明块的格式

    • 选择分组时,保持独立的选择器占用一行;
    • 声明块的左括号{前面加一个空格;
    • 声明块的右括号}应当单独成一行;
    • 声明句的冒号:后面应当加一个空格;
    • 声明句以分号;结尾;
    • 以逗号,分隔的属性值,每个逗号后应添加一个空格;
    • rgb()、rgba()、hsl()、hsla()或 rect()括号内的值,逗号分隔,但逗号后不添加一个空格;
    • 对于属性值或颜色参数,省略小于1的小数前面的0(例如,.5 代替 0.5;-.5px 代替 -0.5px);
    • 十六进制值应该全部小写和尽量简写,例如,#fff 代替 #ffffff;
    • 避免为 0 值指定单位,例如,用margin: 0; 代替margin: 0px;
    /* 错误示范 */
    .selector, .selector-secondary, .selector[type=text] {
        padding:15px;
        margin:0px 0px 15px;
        background-color:rgba(0, 0, 0, 0.5);
        box-shadow:0px 1px 2px #CCC,inset 0 1px 0 #FFFFFF
    }
    
    /* 正确示范 独立的选择器 */
    .selector,
    .selector-secondary,
    .selector[type="text"] {
        padding: 15px;
        margin-bottom: 15px;
        background-color: rgba(0,0,0,.5);
        box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff;
    }
    
  5. 属性的声明顺序

    • Positioning
    • Box Model
    • Typographic
    • Visual

    制定此顺序的原因:
    定位(positioning)可以从正常的文档流中移除元素,还能够覆盖正常的盒模型(box model)的相关样式,因此排在首位。盒模型决定了组件的尺寸和位置,因此排在第二位。其他属性只是影响组件的内部(inside)或者是不影响前两组属性,因此排在后面。
    ```
    /* 正确示范 /
    .declaration-order {
    /
    Positioning */
    position: absolute;
    top: 0;
    right: 0;
    bottom: 0;
    left: 0;
    z-index: 100;

     /* Box model */
     display: block;
     box-sizing: border-box;
     width: 100px;
     height: 100px;
     padding: 10px;
     border: 1px solid #e5e5e5;
     border-radius: 3px;
     margin: 10px;
     float: right;
     overflow: hidden;
    
     /* Typographic */
     font: normal 13px "Helvetica Neue", sans-serif;
     line-height: 1.5;
     text-align: center;
    
     /* Visual */
     background-color: #f5f5f5;
     color: #fff;
     opacity: .8;
    
     /* Other */
     cursor: pointer;
    

    }

  6. 引号的使用

    url(),属性选择符,属性值使用双引号

    /* 错误示范 */
    @import url(//www.google.com/css/maia.css);
    
    html {
        font-family: 'open sans', arial, sans-serif;
    }
    
    /* 正确示范 */
    @import url("//www.google.com/css/maia.css");
    
    html {
        font-family: "open sans", arial, sans-serif;
    }
    
    .selector[type="text"] {
    
    }
    
  7. 媒体查询(media Query)的位置

    • 将媒体查询放在尽可能相关规则的附近,
    • 不要将他们打包放在单独的文件或者文件的底部
    .element { ... }
    .element-avatar { ... }
    .element-selected { ... }
    
    @media (max-width: 768px) {
        .element { ...}
        .element-avatar { ... }
        .element-selected { ... }
    }
    
  8. 关于@importlink

    不用@import,因为他很慢,不但增加了额外的请求数,还会导致不可预料的问题

    解决方法:

    • 使用多个 元素;
    • 通过 Sass 或 Less 类似的 CSS 预处理器将多个 CSS 文件编译为一个文件;
    • 其他 CSS 文件合并工具;
  9. 链接样式的顺序

    a:link -> a:visited -> a:hover -> a:active
    
  10. 组件

    从 Components 的角度思考,将网站的模块都作为一个独立的 Components。

  11. 组件命名

    组件至少使用两个单词命名

    • 点赞(.like-button)
    • 搜索框(.search-form)

6. 文件规范

  1. html,css,js,images归类到约定的目录中
  2. html文件命名:英文命名,后缀为.html将统一页面文件放在同一个目录中,以便后端添加功能时快速的找到对应的页面。
  3. css文件命名:英文命名,后缀为.css共用文件为base.css首页是index.css;其他页面依据需求命名。
  4. js文件命名:英文命名,后缀为.js共用common.js;其他模块按照需求名命名。

7. 通用规范

  1. 所有页面按照统一的格式来写;
  2. 对所有后台请求的返回结果做判断空处理(保证在后台请求失败的情况下,浏览器控制台不会报错);
  3. 所有功能模块写注释,详见下面注释规范;
  4. 处理逻辑一定要尽量简化,抽取公共框架,减少后期维护成本;
  5. tab键用两个空格代替或用两个空格缩进(务必);
  6. 代码行之间尽量不要有空行,重大逻辑转折、语法意义转折,方法分割除外,适当空行增强可读性;
  7. 可使用 W3C HTML/CSS Validator 来验证你的 HTML/CSS 代码有效性;

8. 文件、资源和目录命名约定(适用于所有前端维护的内容和相关目录,(html, css, js, png, gif, jpg, ico)等)

  1. 字母一律小写,必须是英文单词或者汉语拼音,以英语单词优先,多个单词以连字符 - 连接。 只能出现小写引文字母,数字和连字符;
  2. 浏览器广告拦截插件会将含有这些词的作为广告拦截: ad、ads、adv、banner、sponsor、gg、guangg、guanggao等,页面中尽量避免采用以上词汇来命名;
  3. 文件命名总是以字母开头而不是数字,以特殊字符开头命名的文件,一般都有特殊的含义与用处,慎用。
  4. 需要对文件增加前后缀或特定的扩展名(比如 .min.js, .min.css),抑或一串前缀(比如 asdasd.main.min.css)。这种情况下,建议使用点分隔符来区分这些在文件名中带有清晰意义的元数据。

9. css规范

为了便于阅读,css属性书写要遵循本规范。

  1. 为了保证一致性和可扩展性,每个声明应该用分号结束,每个声明换行;

  2. 当使用特定浏览器带有前缀的属性时,通过缩进的方式,让每个属性的值在垂直方向对齐,这样便于多行编辑。
    .selector {
    -webkit-box-shadow: 0 1px 2px rgba(0,0,0,.15);
    box-shadow: 0 1px 2px rgba(0,0,0,.15);
    }

  3. 属性名的冒号后使用一个空格。出于一致性的原因,
    属性和值(但属性和冒号之间没有空格)的之间始终使用一个空格。

  4. 每个规则之间始终有一个空行分隔。

  5. 属性选择器或属性值用双引号(””),而不是单引号(”)括起来。
    URI值(url())不要使用引号。

  6. 为了代码的易读性,在每个声明块的左花括号前添加一个空格;右花括号要单独成行。

  7. 不要在 rgb()、rgba()、hsl()、hsla() 或 rect() 值的内部的逗号后面插入空格。这样利于从多个属性值(既加逗号也加空格)中区分多个颜色值(只加逗号,不加空格)。

  8. 对于属性值或颜色参数,省略小于 1 的小数前面的 0 (例如,.5 代替 0.5;-.5px 代替 -0.5px)。

  9. 与 <link> 标签相比,@import 指令要慢很多,不光增加了额外的请求次数,还会导致不可预料的问题。所以要尽量使用<link>标签引入样式;

10. JavaScript规范

  1. 文件命名可读性强。文件夹、文件的命名与命名空间应能代表代码功能,增强可读性。
  2. 函数命名按照驼峰命名法。
    function funName() {}
  1. 常量要全部大写,变量驼峰命名:
    var VARIABLENAME //常量
    var variableName //变量
  1. 排版缩进采用统一的缩进方式排版代码。缩进为2个空格。
    If(condition1 || condition2) {
    action1;
    } else if (condition3 && condition4) {
    action2;
    } else if (condition5
    && condition6
    && condition7
    && condition8) {
    action2;
    } else {
    default action;
    }

  2. 关键词、条件括弧后面使用空格;运算操作符号两侧使用空格;语句分割符‘,’后面使用空格;
    var name[空格]=[空格]value;
    if空格 {
    }

  3. 左大括号"{"可以居行尾,右大括号"}"单独占一行,居行首
    if (a && b) {
    }

句末必须使用分好结尾;

var fn = function () {
};//这里没有分号的话,脚本解析器会报错!!!
(function () {
   alert(1);
})();
  1. if、while、for、do语句的执行体总是用"{"和"}"括起来

总是使用 var 来声明变量。如不指定 var,变量将被隐式地声明为全局变量,这将对变量难以控制。如果没有声明,变量处于什么定义域就变得不清(可以是在 Document 或 Window 中,也可以很容易地进入本地定义域);
变量声明可以只用一个 var 关键字声明,多个变量用逗号隔开;赋值尽量写在变量声明当中。
使用 === 精确的比较操作符,避免在判断的过程中,由 JavaScript 的强制类型转换所造成的错误(比较的双方必须是同一类型才会有效);
在用if作判断的时候。下列表达式统统返回 false:false, 0, undefined, null, NaN, ''(空字符串).
统一使用单引号(‘),不使用双引号(“)。这在创建 HTML 字符串非常容易辨别;

11. 注释规范

代码注释,永远也不嫌多,特别是在写一些看似琐碎的无关紧要的代码时,由于记忆点不深刻,注释就变得尤为重要了。避免发生过一段时间回头看自己的代码不能立即明白作用;
1.文件注释要标明作者、文件版本、创建/修改时间、重大版本修改记录;
2.函数或者类等都要添加头描述;
3.注释的时候不止写代码都干了些什么,还要加上代码为什么要这么写,背后的考量是什么。当然也可以加入所思考问题或是解决方案的链接地址。
4.代码注释中英文都可以。
/**
* 简述
* 功能详细描述
*
* @param <String> arg1 参数1
* @param <Number> arg2 参数2,默认为0
* @return <Boolean> 看xxx是否成功
*/
function fooFunction (arg1, arg2) {
}

单行注释,写在代码上面;多行注释应有描述;

/*
* 注释操作说明
*/
for( var i = 0; i < 100; i++) {
}

4.为了便于CSS 阅读, css 大模块时间使用区块分割标记;
/****** 注释描述 ********/

12. javascript

12.1. 注释

  1. 原则
    • as short as possible(如无必要,勿增注释):尽量保持代码本身的清晰性可读性
    • as long as necessary(如有必要,尽量详细):合理的注释、空行排版等,可以让代码更易阅读、更具美感。
  2. 单行注释
  3. 多行注释
  4. 函数/方法注释

12.2. JavaScript命名方式

12.3. 命名的词法

12.4. 接口命名规范

12.4.1. true和false布尔表达式

运算式 返回值
null false
undefined false
''(空字符串) false
数字0 false
"0" true
[] true
{} true
undefined == null true
[] == [] false

遗留问题:

12.4.2. 不要在Array上使用for-in循环

for-in 循环只用于object/map/hash循环,
因为for-in循环不是从0到length-1进行遍历的,它遍历的是所有出现在对象和原型链上的key

12.4.3. 二元和三元操作符

12.4.4. &&和||

二元操作符是可短路的,只有在必要的时候才会计算到最后一项。

12.5. jQuery规范

var $myDiv = $("#myDiv");
$myDiv.click(function(){...});

12.5.1. 选择元素

// 错误示范
var $productIds = $("#products .class");

// 正确示范
var $productIds = $("#products").find(".class");

12.5.2. DOM操作

12.5.3. 事件

12.5.4. 链式写法

12.6. 性能优化

12.6.1. 避免使用jQuery实现动画

12.6.2. 避免不必要的DOM操作

最简单优化DOM树查询的方案是:当一个元素出现多次时,将它保存在一个变量中,可以避免多次查询DOM树。

12.6.3. 缓存数组长度

通过存储数组的长度,可以有效避免每次循环重新计算。(新浏览器会自动优化这一过程,旧的浏览器不会)

12.6.4. 异步加载第三方内容

当你无法保证第三方内容(一个视频)可以正常使用时,用异步加载这些代码,避免阻塞整个页面加载。

参考:全部内容来自网络。

上一篇 下一篇

猜你喜欢

热点阅读