[关闭]
@stonezhou 2016-10-19T07:21:16.000000Z 字数 13399 阅读 534

编码规范

Flagwind.UI

目录

原则

不管有多少人共同参与同一项目，确保每一行代码都像同一个人编写的。

命名规则

项目名

项目名以点号分隔。（例如：Flagwind.UI）

目录名

目录名采用全小写形式，多个单词组成时，以中划线分隔，有复数结构时，采用复数命名法。允许使用缩写单词作为目录名。（例如：js、docs、less）

文件名

文件名采用全小写形式，多个单词组成时，采用中划线连接方式。（例如：account-model.js、retina-sprites.css、error-report.html）

编辑器配置

根据以下设置来配置你的编辑器，避免代码不一致的问题。

HTML 规范

基础

  2. <!DOCTYPE html>
  3. <html lang="zh-cn">
  4. <head>
  5.     <meta charset="utf-8" />
  6.     <meta name="renderer" content="webkit" />
  7.     <meta http-equiv="X-UA-Compatible" content="IE=edge" />
  8.     <meta name="viewport" content="width=device-width, initial-scale=1" />
  10.     <title>Untitled</title>
  11.     <meta name="description" content="" />
  12.     <meta name="keywords" content="" />
  14.     <!-- 核心 CSS 文件 -->
  15.     <link rel="stylesheet" href="css/flagwind.min.css" />
  17.     <!-- HTML5 & Media Queries 兼容文件 -->
  18.     <!--[if lt IE 9]>
  19.     <script src="js/html5shiv.min.js"></script>
  20.     <script src="js/respond.min.js"></script>
  21.     <![endif]-->
  22. </head>
  24. <body>
  25.     <div class="container">
  26.         ...
  27.     </div>
  29.     <!-- 核心 JavaScript 文件 -->
  30.     <script src="js/jquery.min.js"></script>
  31.     <script src="js/flagwind.min.js"></script>
  32. </body>
  33. </html>

DOCTYPE

在 HTML 页面中的第一行添加一个标准声明，使其在所有浏览器中拥有一致的展现。虽然 doctype 不区分大小写，但是按照惯例，请将 doctype 大写。

  2. <!DOCTYPE html>

语言属性

根据 HTML5 规范：

强烈建议为 html 根元素指定 lang 属性，从而为文档设置正确的语言。这将有助于语音合成工具确定其所应该采用的发音，有助于翻译工具确定其翻译时所应遵守的规则等等。

这里列出了语言代码表。

  2. <!DOCTYPE html>
  3. <html lang="zh-cn">
  4. </html>

字符编码

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

  2. <meta charset="utf-8" />

IE 兼容模式

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

更多信息，请阅读这篇 Stack Overflow 文章。

  2. <meta http-equiv="X-UA-Compatible" content="IE=Edge" />

引入 CSS 和 JavaScript 文件

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

HTML5 规范链接：

  2. <!-- 引入样式表文件 -->
  3. <link href="css/flagwind.css" rel="stylesheet" />
  5. <!-- 申明内部样式表 -->
  6. <style>
  7.     /* ... */
  8. </style>
  10. <!-- 引入脚本文件 -->
  11. <script src="js/jquery.js"></script>

实用高于完美

尽量遵循 HTML 标准和语义，但是不应该以浪费实用性作为代价。任何时候都要用尽量小的复杂度和尽量少的标签来解决问题。

属性顺序

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

class 用于标识高度可复用组件，理论上他们应该排在第一位。id 用于标识具体组件，应当谨慎使用（例如，页面内的书签），但为了突出 id 的重要性，所以把 id 放到了第一位。

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

布尔（boolean）型属性

布尔型属性可在声明时不赋值（XHTML 规范要求为其赋值，但是 HTML5 规范不需要。），建议采用 属性值=属性名 的方式赋值。

了解更多内容，请参考 WhatWG section on boolean attributes。

  2. <!-- 不写属性代表属性为false -->
  3. <input type="checkbox" />
  5. <!-- 属性值=属性名，代表属性为true -->
  6. <input type="checkbox" checked="checked" />
  8. <select>
  9.     <option value="1" selected="selected">1</option>
  10. </select>

减少标签的数量

编写 HTML 代码时，尽量避免多余的父元素。很多时候，这需要迭代和重构来实现。

  2. <!-- 糟糕的实例 -->
  3. <span class="avatar">
  4.     <img src="..." />
  5. </span>
  7. <!-- 好的实例 -->
  8. <img class="avatar" src="..." />

JavaScript 生成标签

通过 JavaScript 生成的标签让内容变得不易查找、编辑，性能更差。应该尽量避免这种情况的出现。

CSS 规范

基础

更多规则请参考 Wikipedia 中的 CSS语法部分。

  2. /* 糟糕的实例 */
  3. .selector, .selector-secondary, .selector[type=text] {
  4.     padding:15px;
  5.     margin:0px 0px 15px;
  6.     background-color:rgba(0, 0, 0, 0.5);
  7.     box-shadow:0px 1px 2px #CCC,inset 0 1px 0 #FFFFFF
  8. }
  10. /* 好的实例 */
  11. .selector,
  12. .selector-secondary,
  13. .selector[type="text"]
  14. {
  15.     padding: 15px;
  16.     margin-bottom: 15px;
  17.     background-color: rgba(0,0,0,.5);
  18.     box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff;
  19. }

class 命名

  2. /* 糟糕的实例 */
  3. .t { ... }
  4. .red { ... }
  5. .header { ... }
  7. /* 好的实例 */
  8. .fw { ... }
  9. .important { ... }
  10. .fw-header { ... }

选择器

扩展阅读:

  2. /* 糟糕的实例 */
  3. span { ... }
  4. .page-container #stream .stream-item .fw .fw-header .username { ... }
  5. .avatar { ... }
  7. /* 好的实例 */
  8. .avatar { ... }
  9. .fw-header .username { ... }
  10. .fw .avatar { ... }

代码组织

  2. /*
  3.  * Component section heading
  4.  */
  6. .element { ... }
  9. /*
  10.  * Component section heading
  11.  *
  12.  * Sometimes you need to include optional context for the entire component.
  13.  * Do that up here if it's important enough.
  14.  */
  16. .element { ... }
  18. /*
  19.  * Contextual sub-component or modifer
  20.  */
  22. .element-heading { ... }

声明顺序

相关的属性声明应当归为一组，并按照下面的顺序排列：

  1. Positioning（定位）
  2. Box model（盒模型）
  3. Typographic（排版）
  4. Visual（外观）

由于定位（positioning）可以从正常的文档流中移除元素，并且还能覆盖盒模型（box model）相关的样式，因此排在第一位。盒模型紧跟其后，因为他决定了一个组件的尺寸和位置。

其他属性只是影响组件的内部（inside）或者是不影响前两组属性，所以他们排在后面。

关于完整的属性以及他们的顺序，请参考 Recess。

  2. .declaration-order
  3. {
  4.     /* 定位 */
  5.     position: absolute;
  6.     top: 0;
  7.     right: 0;
  8.     bottom: 0;
  9.     left: 0;
  10.     z-index: 100;
  12.     /* 盒模型 */
  13.     display: block;
  14.     float: right;
  15.     width: 100px;
  16.     height: 100px;
  18.     /* 排版 */
  19.     font: normal 13px "Helvetica Neue", sans-serif;
  20.     line-height: 1.5;
  21.     color: #333;
  22.     text-align: center;
  24.     /* 外观 */
  25.     background-color: #f5f5f5;
  26.     border: 1px solid #e5e5e5;
  27.     border-radius: 3px;
  29.     /* 其他 */
  30.     opacity: 1;
  31. }

为了方便查阅，我们将 Recess 的顺序贴了一份出来：

  2. var order =
  3. [
  4.     'position',
  5.     'top',
  6.     'right',
  7.     'bottom',
  8.     'left',
  9.     'z-index',
  10.     'display',
  11.     'float',
  12.     'width',
  13.     'height',
  14.     'max-width',
  15.     'max-height',
  16.     'min-width',
  17.     'min-height',
  18.     'padding',
  19.     'padding-top',
  20.     'padding-right',
  21.     'padding-bottom',
  22.     'padding-left',
  23.     'margin',
  24.     'margin-top',
  25.     'margin-right',
  26.     'margin-bottom',
  27.     'margin-left',
  28.     'margin-collapse',
  29.     'margin-top-collapse',
  30.     'margin-right-collapse',
  31.     'margin-bottom-collapse',
  32.     'margin-left-collapse',
  33.     'overflow',
  34.     'overflow-x',
  35.     'overflow-y',
  36.     'clip',
  37.     'clear',
  38.     'font',
  39.     'font-family',
  40.     'font-size',
  41.     'font-smoothing',
  42.     'osx-font-smoothing',
  43.     'font-style',
  44.     'font-weight',
  45.     'hyphens',
  46.     'src',
  47.     'line-height',
  48.     'letter-spacing',
  49.     'word-spacing',
  50.     'color',
  51.     'text-align',
  52.     'text-decoration',
  53.     'text-indent',
  54.     'text-overflow',
  55.     'text-rendering',
  56.     'text-size-adjust',
  57.     'text-shadow',
  58.     'text-transform',
  59.     'word-break',
  60.     'word-wrap',
  61.     'white-space',
  62.     'vertical-align',
  63.     'list-style',
  64.     'list-style-type',
  65.     'list-style-position',
  66.     'list-style-image',
  67.     'pointer-events',
  68.     'cursor',
  69.     'background',
  70.     'background-attachment',
  71.     'background-color',
  72.     'background-image',
  73.     'background-position',
  74.     'background-repeat',
  75.     'background-size',
  76.     'border',
  77.     'border-collapse',
  78.     'border-top',
  79.     'border-right',
  80.     'border-bottom',
  81.     'border-left',
  82.     'border-color',
  83.     'border-image',
  84.     'border-top-color',
  85.     'border-right-color',
  86.     'border-bottom-color',
  87.     'border-left-color',
  88.     'border-spacing',
  89.     'border-style',
  90.     'border-top-style',
  91.     'border-right-style',
  92.     'border-bottom-style',
  93.     'border-left-style',
  94.     'border-width',
  95.     'border-top-width',
  96.     'border-right-width',
  97.     'border-bottom-width',
  98.     'border-left-width',
  99.     'border-radius',
  100.     'border-top-right-radius',
  101.     'border-bottom-right-radius',
  102.     'border-bottom-left-radius',
  103.     'border-top-left-radius',
  104.     'border-radius-topright',
  105.     'border-radius-bottomright',
  106.     'border-radius-bottomleft',
  107.     'border-radius-topleft',
  108.     'content',
  109.     'quotes',
  110.     'outline',
  111.     'outline-offset',
  112.     'opacity',
  113.     'filter',
  114.     'visibility',
  115.     'size',
  116.     'zoom',
  117.     'transform',
  118.     'box-align',
  119.     'box-flex',
  120.     'box-orient',
  121.     'box-pack',
  122.     'box-shadow',
  123.     'box-sizing',
  124.     'table-layout',
  125.     'animation',
  126.     'animation-delay',
  127.     'animation-duration',
  128.     'animation-iteration-count',
  129.     'animation-name',
  130.     'animation-play-state',
  131.     'animation-timing-function',
  132.     'animation-fill-mode',
  133.     'transition',
  134.     'transition-delay',
  135.     'transition-duration',
  136.     'transition-property',
  137.     'transition-timing-function',
  138.     'background-clip',
  139.     'backface-visibility',
  140.     'resize',
  141.     'appearance',
  142.     'user-select',
  143.     'interpolation-mode',
  144.     'direction',
  145.     'marks',
  146.     'page',
  147.     'set-link-source',
  148.     'unicode-bidi',
  149.     'speak'
  150. ]

不要使用 @import

与 <link> 标签相比，@import 指令要慢很多，不光增加了额外的请求次数，还会导致不可预料的问题。替代办法有以下几种：

更多信息，请阅读 Steve Souders 的文章。

  2. <!-- 推荐使用 link 元素 -->
  3. <link rel="stylesheet" href="layout.css">
  5. <!-- 避免使用 @import 指令 -->
  6. <style>
  7.     @import url("layout.css");
  8. </style>

媒体查询（Media query）的位置

将媒体查询放在尽可能相关规则的附近。不要将他们放在文档底部或者打包放在一个单一样式文件中。如果你把他们分开了，将来只会被大家遗忘。下面给出一个典型的示例：

  2. .element { ... }
  3. .element-avatar { ... }
  4. .element-selected { ... }
  6. @media (min-width: 480px)
  7. {
  8.     .element { ...}
  9.     .element-avatar { ... }
  10.     .element-selected { ... }
  11. }

带前缀的属性

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

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

单条声明的声明块

在一个声明块中只包含一条声明的情况下，为了易读性和快速编辑可以考虑移除其中的换行。所有包含多条声明的声明块应该分为多行。

这样做的关键因素是错误检测 - 例如，一个 CSS 验证程序显示你在 183 行有一个语法错误,如果是一个单条声明的行，那就是他了。在多个声明的情况下，你必须为哪里出错了费下脑子。

  2. /* 单条声明 */
  3. .span1 { width: 60px; }
  4. .span2 { width: 140px; }
  5. .span3 { width: 220px; }
  7. /* 多条声明 */
  8. .sprite
  9. {
  10.     display: inline-block;
  11.     width: 16px;
  12.     height: 15px;
  13.     background-image: url(../images/sprite.png);
  14. }

简写形式的属性声明

在需要显示地设置所有值的情况下，应当尽量限制使用简写形式的属性声明。常见的滥用简写属性声明的情况如下：

大部分情况下，我们不需要为简写形式的属性声明指定所有值。例如，HTML 的 heading 元素只需要设置上、下边距（margin）的值，因此，在必要的时候，只需覆盖这两个值就可以。过度使用简写形式的属性声明会导致代码混乱，并且会对属性值带来不必要的覆盖从而引起意外的副作用。

Mozilla Developer Network 有一篇对不熟悉属性简写及其行为的人来说很棒的关于 shorthand properties 的文章。

  2. /* 糟糕的实例 */
  3. .element
  4. {
  5.     margin: 0 0 10px;
  6.     background: red;
  7.     background: url("image.jpg");
  8.     border-radius: 3px 3px 0 0;
  9. }
  11. /* 好的实例 */
  12. .element
  13. {
  14.     margin-bottom: 10px;
  15.     background-color: red;
  16.     background-image: url("image.jpg");
  17.     border-top-left-radius: 3px;
  18.     border-top-right-radius: 3px;
  19. }

LESS 和 SASS 中的嵌套

避免不必要的嵌套。可以进行嵌套，不意味着你应该这样做。只有在需要给父元素增加样式并且同时存在多个子元素时才需要考虑嵌套。

  2. /* 糟糕的实例 */
  3. .table > thead > tr > th { … }
  4. .table > thead > tr > td { … }
  6. /* 好的实例 */
  7. .table > thead > tr
  8. {
  9.     > th { … }
  10.     > td { … }
  11. }

注释

代码是由人编写并维护的。请确保你的代码能够自然描述、注释良好并且易于他人理解。好的代码注释能够传达上下文关系和代码目的。不要简单地重申组件或 class 名称。

对于较长的注释，务必书写完整的句子；对于一般性注解，可以书写简洁的短语。

  2. /* 糟糕的实例 */
  4. /*
  5.  * Modal header
  6.  */
  7. .modal-header
  8. {
  9.     ...
  10. }
  12. /* 好的实例 */
  14. /*
  15.  * 包含 .modal-title 和 .modal-close 的容器。
  16.  */
  17. .modal-header
  18. {
  19.     ...
  20. }

JavaScript 规范

基础

命名

  2. function Animal()
  3. {
  4.     this._name = null;
  6.     this.getName = function()
  7.     {
  8.         var min = 111111,       //随机数最小值
  9.             max = 999999;       //随机数最大值
  11.         if(!this._name)
  12.         {
  13.             return Math.floor(Math.random() * (max - min)) + min;
  14.         }
  16.         return this._name;
  17.     };
  19.     this.setName = function(name)
  20.     {
  21.         this._name = name;
  22.     };
  23. }

空行

缩进

缩进的单位为4个空格，规则也很简单——花括号里面的东西。这就意味着函数体、循环 (do, while, for, for-in)、if、switch，以及对象字面量中的对象属性。下面的代码就是使用缩进的示例：

  2. function outer(a, b)
  3. {
  4.     var c = 1,
  5.         d = 2,
  6.         inner;
  8.     if(a > b)
  9.     {
  10.         inner = function()
  11.         {
  12.             return {
  13.                 r : c - d
  14.             };
  15.         };
  16.     }
  17.     else
  18.     {
  19.         inner = function()
  20.         {
  21.             return {
  22.                 r : c + d
  23.             };
  24.         };
  25.     }
  27.     return inner;
  28. }

空格

空格的使用同样有助于改善代码的可读性和一致性。适合使用空格的地方包括：

花括号

花括号 {} 应总被使用，即使在它们为可选的时候。虽然在 if 或者 for 中如果语句仅一条，花括号是不需要的，但是你还是应该总是使用它们，这会让代码更有持续性和易于更新。

想象下你有一个只有一条语句的 for 循环，你可以忽略花括号，而没有解析的错误。

  2. // 糟糕的实例
  3. for(var i = 0; i < 10; i++)
  4.     alert(i);

但是，如果，后来，主体循环部分又增加了行代码：

  2. // 糟糕的实例
  3. for(var i = 0; i < 10; i++)
  4.     alert(i);
  5.     alert(i + " is " + (i % 2 ? "odd" : "even"));

第二个 alert 已经在循环之外，缩进可能欺骗了你。为了长远打算，最好总是使用花括号，即使只有一行代码：

  2. // 好的实例
  3. for(var i = 0; i < 10; i++)
  4. {
  5.     alert(i);
  6. }

因此，涉及 if，for，while，do...while，try...catch...finally 的地方都必须使用花括号。

for 语句

  2. var name,                           // 属性名称
  3.     person,                         // Person 类的实例
  4.     list = [10, 12, 13, 14, 15];    // 整型数组
  6. // 普通循环实例
  7. for(var i = 0, length = list.length; i < length; i++)
  8. {
  9.     console.log(list[i]);
  10. }
  12. // for in 循环实例
  13. for(name in person)
  14. {
  15.     // 判断 person 对象是否拥有指定的属性。
  16.     if(person.hasOwnProperty(name))
  17.     {
  18.         console.log("Property name is " + name);
  19.         console.log("Property value is " + person[name]);
  20.     }
  21. }

switch 语句

case 需要缩进，在 break 与之后的 case 中间需要一个换行。

  2. switch(condition)
  3. {
  4.     case "first":
  5.         // code
  6.         break;
  8.     case "third":
  9.         // code
  10.         break;
  12.     default:
  13.     // code
  14. }

null 关键字

使用场景

非使用场景

undefined 关键字

  2. var person;
  4. // 糟糕的实例
  5. if(person === undefined)
  6. {
  7.     ...
  8. }
  10. // 好的实例
  11. if(typeof person === "undefined")
  12. {
  13.     ...
  14. }

注释

单行注释

  2. // 好的实例
  3. if(condition)
  4. {
  5.     // 条件成立，执行 allowed 函数。
  6.     allowed();
  7. }
  9. var name = "jason";    // 双斜线距离分号一个缩进，双斜线后始终保留一个空格。

多行注释

什么时候使用多行注释？

多行注释的标准？

  2. /*
  3.  * 注释内容与星标前保留一个空格
  4.  */

文档注释

请按照如下场景添加文档注释，具体用到的标签（例如：@param）请参考 JSDoc。

  2. /*!
  3.  * Flagwind.UI(Alert) v1.0.1
  4.  * Copyright 2014 Flagwind Inc. All rights reserved.
  5.  * Licensed under the MIT License.
  6.  * https://github.com/Flagwind/Flagwind.UI/blob/master/LICENSE
  7.  *
  8.  * @author jason
  9.  * @email jasonsoop@gmail.com
  10. !*/
  12. +function($)
  13. {
  14.     "use strict";
  16.     /**
  17.      * @public @class 初始化 Alert 类的新实例。
  18.      * @param {object=} options 配置选项。
  19.      * @return {object} this
  20.      */
  21.     var Alert = function(options)
  22.     {
  23.         return this;
  24.     }
  26.     /**
  27.      * @public @property {string} 版本号
  28.      */
  29.     Alert.VERSION = "1.0.1";
  31.     /**
  32.      * @public 显示提示框。
  33.      * @param {(string|number)} duration 一个字符串或数字用于控制动画的时长。
  34.      * @return {object} this
  35.      */
  36.     Alert.prototype.show = function(duration)
  37.     {
  38.         return this;
  39.     }
  41. }(jQuery);
添加新批注
在作者公开此批注前，只有你和作者可见。
回复批注