• 基本原则
    • 结构、样式、行为分离
    • 缩进
    • 文件编码
    • 一律使用小写字母
    • 省略外链资源 URL 协议部分
    • 统一注释
      • HTML 注释
      • CSS 注释
      • JavaScript 注释
  • 代码验证

    基本原则

    结构、样式、行为分离

    尽量确保文档和模板只包含 HTML 结构，样式都放到样式表里，行为都放到脚本里。

    缩进

    统一两个空格缩进（总之缩进统一即可），不要使用 Tab 或者 Tab、空格混搭。

    文件编码

    使用不带 BOM 的 UTF-8 编码。

    • 在 HTML中指定编码 <meta charset="utf-8"> ；
    • 无需使用 @charset 指定样式表的编码，它默认为 UTF-8 （参考 @charset"">@charset）；

    一律使用小写字母

    1. <!-- Recommended -->
    2. <img src="google.png" alt="Google">
    4. <!-- Not recommended -->
    5. <A HREF="/">Home</A>
    1. /* Recommended */
    2. color: #e5e5e5;
    4. /* Not recommended */
    5. color: #E5E5E5;

    省略外链资源 URL 协议部分

    省略外链资源（图片及其它媒体资源）URL 中的 http / https 协议，使 URL 成为相对地址，避免 Mixed Content 问题，减小文件字节数。

    其它协议（ftp 等）的 URL 不省略。

    1. <!-- Recommended -->
    2. <script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>
    4. <!-- Not recommended -->
    5. <script src="http://www.google.com/js/gweb/analytics/autotrack.js"></script>
    1. /* Recommended */
    2. .example {
    3.   background: url(//www.google.com/images/example);
    4. }
    6. /* Not recommended */
    7. .example {
    8.   background: url(http://www.google.com/images/example);
    9. }

    统一注释

    通过配置编辑器，可以提供快捷键来输出一致认可的注释模式。

    HTML 注释

    • 模块注释

      1. <!-- 文章列表列表模块 -->
      2. <div class="article-list">
      3. ...
      4. </div>

    • 区块注释

      1. <!--
      2. @name: Drop Down Menu
      3. @description: Style of top bar drop down menu.
      4. @author: Ashu(Aaaaaashu@gmail.com)
      5. -->
    CSS 注释

    组件块和子组件块以及声明块之间使用一空行分隔，子组件块之间三空行分隔；

    1. /* ==========================================================================
    2.    组件块
    3.  ============================================================================ */
    5. /* 子组件块
    6.  ============================================================================ */
    7. .selector {
    8.   padding: 15px;
    9.   margin-bottom: 15px;
    10. }
    14. /* 子组件块
    15.  ============================================================================ */
    16. .selector-secondary {
    17.   display: block; /* 注释*/
    18. }
    20. .selector-three {
    21.   display: span;
    22. }
    JavaScript 注释
    • 单行注释

    必须独占一行。// 后跟一个空格，缩进与下一行被注释说明的代码一致。

    • 多行注释

    避免使用 /*...*/ 这样的多行注释。有多行注释内容时，使用多个单行注释。

    • 函数/方法注释
    1. 函数/方法注释必须包含函数说明，有参数和返回值时必须使用注释标识。；
    2. 参数和返回值注释必须包含类型信息和说明；
    3. 当函数是内部函数，外部不可访问时，可以使用 @inner 标识；
    1. /**
    2.  * 函数描述
    3.  *
    4.  * @param {string} p1 参数1的说明
    5.  * @param {string} p2 参数2的说明，比较长
    6.  *     那就换行了.
    7.  * @param {number=} p3 参数3的说明（可选）
    8.  * @return {Object} 返回值描述
    9.  */
    10. function foo(p1, p2, p3) {
    11.     var p3 = p3 || 10;
    12.     return {
    13.         p1: p1,
    14.         p2: p2,
    15.         p3: p3
    16.     };
    17. }
    • 文件注释

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

    1. /**
    2.  * @fileoverview Description of file, its uses and information
    3.  * about its dependencies.
    4.  * @author user@meizu.com (Firstname Lastname)
    5.  * Copyright 2015 Meizu Inc. All Rights Reserved.
    6.  */

    代码验证

    • 使用 W3C HTML Validator 来验证你的HTML代码有效性；
    • 使用 W3C CSS Validator 来验证你的CSS代码有效性；

    代码验证不是最终目的，真的目的在于让开发者在经过多次的这种验证过程后，能够深刻理解到怎样的语法或写法是非标准和不推荐的，即使在某些场景下被迫要使用非标准写法，也可以做到心中有数。