前端代码规范

Posted 岛与_暮歌

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了前端代码规范相关的知识，希望对你有一定的参考价值。

通用规范

  1. tab键用两个空格代替
    　　因为在不同系统的编辑工具对tab解析不一样，windows下的tab键是占四个空格的位置，而在linux下会变成占八个空格的位置（除非你 自己设定了tab键所占的位置长度）。
  2. 每个样式属性或者每句代码后加 ";"
    方便压缩工具"断句"。

html规范

HTML5 doctype

为每个 HTML 页面的第一行添加标准模式（standard mode）的声明，这样能够确保在每个浏览器中拥有一致的展现。

:::html
<!DOCTYPE html>
<html>
  <head>
  </head>
</html>

字符编码

通过明确声明字符编码，能够确保浏览器快速并容易的判断页面内容的渲染方式。这样做的好处是，可以避免在 HTML 中使用字符实体标记（character entity），从而全部与文档编码一致（约定一致采用UTF-8编码）。

:::html
<head>
  <meta charset="UTF-8">
</head>

文档模板

:::html
<!DOCTYPE HTML>
<html>
    <head>
        <meta charset="utf-8" />
        <title>Sample page</title>
        <link rel="stylesheet" href="css_example_url" />
        <script src="js_example_url"></script>
    </head>
    <body>
        <section id="page">
            <header id="header">
            页头
            </header>
            <section id="body">
            主体
            </section>
            <footer id="footer">
            页尾
            </footer>
        </section>
        <script>
        // 你的代码
        </script>
    </body>
</html>

IE 兼容模式

IE 支持通过特定的 <meta> 标签来确定绘制当前页面所应该采用的 IE 版本。除非有强烈的特殊需求，否则最好是设置为 edge mode，从而通知 IE 采用其所支持的最新的模式。

:::html
<meta http-equiv="X-UA-Compatible" content="IE=Edge">

元素

  1. html5元素

    • section 表示文档中的节、区段，可以和h1-h6一起来显示文档结构
    • article 表示一块比较独立的内容或者主题内容，块级元素，比如blog的内容，报纸的文章
    • aside 表示article以外的内容，而且应该和article有一定的关系，块级元素
    • hgroup 表示一个文档、区段(section)的标题组合
    • header 表示页眉,页头
    • footer 表示页脚
    • nav 表示导航内容
    • figure 表示以相对独立的或外引的元素，如img video

    • figcaption 表示 figure内容的标题

        :::html
  <!-- hgroup 示例 -->
  <hgroup>
  <h1>文档主标题</h1>
  <h2>文档副标题</h2>
  </hgroup>

  <!-- figure 示例 -->
  <figure>
   <video src="ogg"></video>
   <figcaption>Example</figcaption>
  </figure>

  <figure>
   <img src="img" alt="Example image" />
   <figcaption>Example image</figcaption>
  </figure>

  2. 结构性元素

    • p 表示段落。只能包含内联元素，不能包含块级元素;
    • div 本身无特殊含义，可用于布局。几乎可以包含任何元素;
    • br 表示换行符;
    • hr 表示水平分割线;
    • h1-h6 表示标题。其中 h1 用于表示当前页面最重要的内容的标题;
    • blockquote 表示引用，可以包含多个段落。请勿纯粹为了缩进而使用 blockquote，大部分浏览器默认将 blockquote 渲染为带有左右缩进;
    • pre 表示一段格式化好的文本;

  3. 头部元素

    • title 每个页面必须有且仅有一个 title 元素;
    • base 可用场景：首页、频道等大部分链接都为新窗口打开的页面;
    • link link 用于引入 css 资源时，可省去 media(默认为all) 和 type(默认为text/css) 属性;
    • style type 默认为 text/css，可以省去;
    • script type 属性可以省去; 不赞成使用lang属性; 不要使用古老的<!– //–>这种hack脚本, 它用于阻止第一代浏览器（Netscape 1和Mosaic）将脚本显示成文字;
    • noscript 在用户代理不支持 javascript 的情况下提供说明;

  4. 文本元素

    • a a 存在 href 属性时表示链接，无 href 属性但有 name 属性表示锚点;
    • em,strong em 表示句意强调，加与不加会引起语义变化，可用于表示不同的心情或语调; strong 表示重要性强调，可用于局部或全局，strong强调的是重要性，不会改变句意;
    • abbr 表示缩写;
    • sub,sup 主要用于数学和化学公式，sup还可用于脚注;
    • span 本身无特殊含义;
    • ins,del 分别表示从文档中增加(插入)和删除

  5. 媒体元素

    • img 请勿将img元素作为定位布局的工具，不要用他显示空白图片; 必要时给img元素增加alt属性;
    • object 可以用来插入Flash;

  6. 列表元素

    • dl 表示关联列表，dd是对dt的解释; dt和dd的对应关系比较随意：一个dt对应多个dd、多个dt对应一个dd、多个dt对应多个dd，都合法; 可用于名词/单词解释、日程列表、站点目录;
    • ul 表示无序列表;
    • ol 表示有序列表, 可用于排行榜等;
    • li 表示列表项，必须是ul/ol的子元素;

  7. 表单元素

    • 推荐使用 button 代替 input，但必须声明 type;
    • 表单元素的 name 不能设定为 action, enctype, method, novalidate, target, submit 会导致表单提交混乱

属性顺序

  1. HTML 属性应当按照以下给出的顺序依次排列，确保代码的易读性。

    • class
    • id 、 name
    • data-*
    • src、for、 type、 href
    • title、alt
    • aria-*、 role

  2. class用于标识高度可复用组件，因此应该排在首位。id 用于标识具体组件，应当谨慎使用（例如，页面内的书签），因此排在第二位。如：

    :::html
<a class="..." id="..." data-modal="toggle" href="#">
 Example link
</a>
 <input class="form-control" type="text">
 <img src="..." alt="...">

文件和目录命名约定

  1. 一律小写，必须是英文单词或者汉语拼音，以英语单词优先，多个单词以连字符 ( - ) 连接。 只能出现小写引文字母，数字和连字符。
  2. 很多浏览器会将含有这些词的作为广告拦截： ad、ads、adv、banner、sponsor、gg、guangg、guanggao等 页面中尽量避免采用以上词汇来命名。
  3. 该命令规范适用于所有前端维护的内容和相关目录。(html, css, js, png, gif, jpg, ico)。

空格/标签/注释

  1. 用两个空格来代替制表符（tab） —— 这是唯一能保证在所有环境下获得一致展现的方法；
  2. 嵌套元素应当缩进一次 —— 即两个空格；
  3. 对于属性的定义，确保全部使用双引号，绝不要使用单引号；
  4. 不要省略可选的结束标签，如：</li>,</body>；
  5. 习惯性书写注释，方便日后维护；

文件编码约定

所有文件统一采用UTF-8无BOM编码。换行格式为 unix 格式。

id和class命名约定

  1. id 和 class 的命名基本原则: 内容优先，表现为辅。首先根据内容来命名，如:#header,#footer,.main-nav.如根据内容无法找到合适的命名，可以再结合表现进行命名，如：col-main, col-sub, col-extra,blue-box
  2. id 和 class 的名称一律小写，多个单词以连字符连接，如： main-wrap
  3. id 和 class 的名称只能出现，小写字母，数字和连字符( - )(js钩子除外)
  4. id 和 class 的名称尽量使用英文单词命名,如确实找不到合适的单词，可以使用拼音，如：zhidao-com
  5. 在不影响语意的情况下，id 和 class 的名称 可以适当使用缩写，如: col, nav, hd, bd, fd( 缩写只用来表示结构，不允许写任何样式)。不要自造缩写。
  6. class 对于选中命名.selected;对于hover，支持伪类使用:hover，不支持的使用 .hover，隐藏使用.hide 。
  7. id 和 class 的选择，如果只使用一次，使用id,如果使用多次使用class，如果需要和js交互，使用id,如果需要交互并且页面中有大量重复，请参见下一条。
  8. 对于作为js钩子的 id 和 class 命名规则为以”J_“开头(J,象形钩子的形状)，后面加上原应有的命名，在使用class的时候需要放在最前面。如:class="J_tab-content some-mod-content"。（注意：钩子，不允许在css中定义任何的样式效果）
  9. 很多浏览器会将含有这些词的作为广告拦截： ad、ads、adv、banner、sponsor、gg、guangg、guanggao等 页面中尽量避免采用以上词汇来命名。

文件引用

  1. 页面中不允许出现css内容(包括行内样式和style)
  2. 每个页面中至多包括3个css文件，1个 产品级 1个模块级 1个页面级别

选择器

  1. 命名比较短的词，或者缩写的不允许直接定义样式，如：.title,.hd,.bd,.body.必须用上级节点进行限定,如：.recommend-mod .title

通用结构

  1. 页面中的块采用如下结构 
    :::html
<div class="mod recommend-mod">
 <div class="hd recommend-title">Tilte </div>
 <div class="bd recommend-body">contents</div>
 <div class="ft recommend-footer">footer </div>
</div>

没有内容的部分可以省略，其中用来表示结构的 mod hd bd ft 不允许直接定义样式（避免嵌套带来样式问题）,需要定义样式的时候需要另外增加class以控制样式如：

:::html    
<div class="mod recommend-mod">
  <div class="hd recommend-title">Tilte </div>
  <div class="bd recommend-body">contents</div>
  <div class="ft recommend-footer">footer </div>
</div>

当2个以上的结构不存在的时候可以不是采用此结构，如，没有hd和ft,bd也可以省略

多选择器规则之间换行
当样式针对多个选择器时每个选择器占一行

/ 推荐的写法 /
a.btn,
input.btn,
input[type="button"] {
......
}

z-index

  1. 自己写的z-index的值不能超过 100 (通用组的除外)
  2. 页面中的元素内容的z-index不能超过10(popup poptip除外)，需要按照内容定义1 2 3 4不允许直接使用如1000，9999
  3. popup poptip的z-index需要按照内容使用 99以下，10以上的值（11,12,13，也可以小于10），不允许直接使用1000，9999之类大值

现在通用z-index记录,使用时请避开和灵活使用

z-index 使用者 类型
<10 page-content 页面级别
>10, <99 page-popup 页面级别
20 usercard用户名片 common通用
  MSG气泡消息 common通用
  Dialog-Cover common通用
  Dialog common通用

css规范

css属性顺序

  1. 显示属性；
  2. 元素位置；
  3. 元素属性；
  4. 元素内容属性；

  5. css书写顺序：

    :::html
例子:
.header {
 /* 显示属性 */
 display || visibility
 list-style
 position
 top || right || bottom || left
 z-index
 clear
 float

 /* 自身属性 */
 width
 max-width || min-width
 height
 max-height || min-height
 overflow || clip
 margin 
 padding
 outline
 border
 background

 /* 文本属性 */
 color
 font
 text-overflow
 text-align
 text-indent
 line-height
 white-space
 vertical-align
 cursor
 content
}

css写法

  1. 小图片（必须）sprite 合并
  2. 每个样式属性后加 ";"

  3. 禁止将样式写为单行

    如
    .hotel-content {margin: 10px; background-color: #efefef;}
    单行显示不好注释，不好备注，这应该是压缩工具的活儿~

  4. 禁止使用行内（inline）样式

  5. 禁止使用"*"来选择元素

    /*别这样写*/
    * {
    margin: 0;
    padding: 0;
    }

    这样写是没有必要的，一些元素在浏览器中默认有margin或padding值，但是只是部分元素，没有必要将所有元素的margin、padding值都置为0。

  6. 带前缀的属性
    当使用特定浏览器带有前缀的属性时，通过缩进的方式，让每个属性的值在垂直方向对齐，这样便于多行编辑。如： 

    .selector {
  -webkit-box-shadow: 0 1px 2px rgba(0,0,0,.15);
       box-shadow: 0 1px 2px rgba(0,0,0,.15);
}

  7. 优化css选择器
    css选择器是从右边到左边进行匹配的。如：

    #header a {
 color: #444;
}

    浏览器会检查整个文档中的所有链接，然后浏览器并不仅仅检查每个链接的父元素，还要遍历文档树去查找 id 为 header 的祖先元素，如果被评估的链接不是 header 的后代，那么浏览器就要向上一级遍历知道文档的根节点。针对此问题，有以下几个解决方法：

    • 避免使用通配规则
      除了传统意义的通配选择符之外还包括相邻兄弟选择符, 子选择符, 后代选择符和属性选择符。推荐id、class和标签选择符。
    • 不要限定id选择符
      页面中指定一个id只能对应一个元素，所以没有必要添加额外添加限定符，如： div#header ，应该简化为： #header（提权的除外）。
    • 不要限定类选择器
      不要用具体的标签限定类选择符，而是根据实际情况对类名进行扩展。例如： ul.recommend ，改成 .recommend-list 或者 .list-recommend。
    • 让规则越具体越好
      尽量不要使用 ul li a 这样长的选择符，最好使用 .list-anchor 之类的选择符。
    • 避免使用后代选择符
      通常处理后代选择符开销最高，使用字选择符更高效，最好使用下一条代替。
    • 避免使用标签子选择符
      如果有如： #header > li > a，这样基于子标签的自选择符，那么应该使用一个class来关联每个元素如： .header-anchor。尽量使用具体的类代替子选择符。

前端规范之JavaScript

命名规范

  1. 文件命名可读性强
    文件夹、文件的命名与命名空间应能代表代码功能，可读性强。

  2. 函数命名
    驼峰命名方式

    :::javascript
function funName() {}

  3. 常量
    大写

     :::javascript
 var VARIABLENAME

  4. 变量
    驼峰命名

    :::javascript
var variableName

编码规则

  1. 排版缩进
    采用统一的缩进方式排版代码。缩进为2个ASCII空格

    :::javascript
If(condition1 || condition2) {
  action1;
} else if (condition3 && condition4) {
 action2;
} else if (condition5
       && condition6
       && condition7
       && condition8) {
 action2;
} else {
 default action;
}

  2. 关键词、条件括弧后面使用空格；运算操作符号两侧使用空格；语句分割符‘,’后面使用空格

    :::javascript
var name[空格]=[空格]value;
if[空格](a,[空格]b) {
}

  3. 左大括号"{"可以居行尾，也可写在下行首（独自一行）；右大括号"}"单独占一行，居行首

    :::javascript
if (a && b) {
 }
------------------------
if (a && b) 
{
}

  4. 句末必须用分号结尾

    :::javascript
var fn = function () {
};//这里没有分号的话，脚本解析器会报错！！！
(function () {
   alert(1);
})();

  5. 单行过长应在适当位置予以换行,增强可读性
    if 语句括号中的条件若过多过长，应予以折行；折行后，||、&& 等符号应与 “(” 后的第一个字母纵向对齐

    :::javascript
if (condition1 
 && condition2 
 || condition3) {
}

  6. if、while、for、do语句的执行体总是用"{"和"}"括起来，即使在其结构体内只有一条语句

    :::javascript
if (s==100) {
 alert(‘shit!‘);
}

  7. 语法意义相互独立的代码将用空行分隔

    :::javascript
a++; b++;   //！！！避免同一行书写两个表达式
if (a > b) {
 value = a;  //行间不用空行间隔
}

var variableName = value;   //与上一代码行使用空行间隔

注释规范

  1. 文件注释

    • 文件注释要标明作者、文件版本、创建/修改时间、重大版本修改记录
    • 函数描述

    • 文件版本、创建或者修改时间、功能、作者

       :::javascript
 /**
 * @file Image.js
 * @description 功能详细描述
 */

    • 函数或者类等都要添加头描述

       :::javascript
 /**
 * 简述
 *
 * 功能详细描述
 *
 * @param <String> arg1 参数1
 * @param <Number> arg2 参数2，默认为0
 * @return <Boolean> 看xxx是否成功
 */
 function fooFunction (arg1, arg2) {
 }

  2. 操作注释

    • 单行注释,写在代码上面

    • 多行注释

      :::javascript
/*
* 注释操作说明
*/
for( var i = 0; i < obj.lenght; i++) {
}

    • 注释标签参考

标签 描述
@addon 把一个函数标记为另一个函数的扩张，另一个函数的定义不在源文件中。
@argument 用大括号中的自变量类型描述一个自变量。
@author 函数/类作者的姓名。
@base 如果类是继承得来，定义提供的类名称。
@class 用来给一个类提供描述，不能用于构造器的文档中。
@constructor 描述一个类的构造器。
@deprecated 表示函数/类已被忽略。
@exception 描述函数/类产生的一个错误。
@exec  
@extends 表示派生出当前类的另一个类。
@fileoverview 表示文档块将用于描述当前文件。这个标签应该放在其它任何标签之前。
@final 指出函数/类。
@ignore 让jsdoc忽视随后的代码。
@link 类似于@link标签，用于连接许多其它页面。
@member 定义随后的函数为提供的类名称的一个成员。
@param 用大括号中的参数类型描述一个参数。
@private 表示函数/类为私有，不应包含在生成的文档中。
@requires 表示需要另一个函数/类。
@return 描述一个函数的返回值。
@returns 描述一个函数的返回值。
@see 连接到另一个函数/类。
@throws 描述函数/类可能产生的错误。
@type 指定函数/成员的返回类型。
@version 函数/类的版本号。

条件判断的陷阱

  1. 在if判断中，使用===作比较,避免掉入==造成的陷阱

    • 在条件判断时，这样的一些值表示false：null，undefined，字符串‘‘，数字0，NaN

    • 而在==时，则会有一些让人难以理解的陷阱,如：

      (function () { 
  var undefined; 
  undefined == null; // true 
  1 == true; //true 
  2 == true; // false 
  0 == false; // true 
  0 == ‘‘; // true 
  NaN == NaN;// false 
  [] == false; // true 
  [] == ![]; // true 
})();

    • 对于不同类型的 == 判断，有这样一些规则，顺序自上而下：

      1.undefined与null相等
      2.一个是number一个是string时，会尝试将string转换为number
      3.尝试将boolean转换为number，0或1
      4.尝试将Object转换成number或string，取决于另外一个对比量的类型

所以，对于0、空字符串的判断，建议使用 === 。===会先判断两边的值类型，类型不匹配时为false。

简单类型转换

  1. number to string的转换，建议使用 1 + ‘‘或String(1)，不使用new String(1)或1.toString()的方式。

  2. string to number的转换，建议使用parseInt，必须显式指定第二个参数的进制。下面的例子展示了不指定进制的风险：

    parseInt(‘08‘); // 0 
parseInt(‘08‘, 10); //8

  3. float to integer的转换，建议使用Math.floor/Math.round/Math.ceil方法，不使用parseInt。

字符串拼接
字符串拼接，应使用数组保存字符串片段，使用时调用join方法。避免使用+或+=的方式拼接较长的字符串，每个字符串都会使用一个小的内存片段，过多的内存片段会影响性能。如:

不好的拼接方式，+=

var str = ‘‘; 
for (var i = 0, len = list.length; i < len; i++) { 
  str+= ‘<div>‘ + list[i] + ‘</div>‘; 
} 
dom.innerHTML = str;

正确拼接方式，Array的push+join

var str = []; 
for (var i = 0, len = list.length; i < len; i++) { 
  str.push(‘<div>‘+ list[i] + ‘</div>‘); 
} 
dom.innerHTML = str.join(‘‘);

获取元素

  1. 获取单个元素

    • 通常，我们使用document.getElementById来获取dom元素，避免使用document.all。document.getElementById是标准方法，兼容所有浏览器

      ie浏览器会混淆元素的id和name属性，document.getElementById可能获得不期望的元素。
在对元素的id与name属性的命名需要非常小心，应使用不同的命名法。
下面是一个name与id冲突的例子：

<input type="text" name="test"> <div id="test"></div>
<button onclick="alert(document.getElementById(‘test‘).tagName)"></button>
<!-- ie6下为INPUT -->



文／熊猫猫超人（简书作者）
原文链接：http://www.jianshu.com/p/8d291d823cc0
著作权归作者所有，转载请联系作者获得授权，并标注“简书作者”。

以上是关于前端代码规范的主要内容，如果未能解决你的问题，请参考以下文章

前端代码编写规范

前端开发常用代码片段（中篇）

前端防扒代码片段

前端防扒代码片段

前端防扒代码片段

前端防扒代码片段