Web Styleguide – Style guide to harmonize HTML, Javascript and CSS / SASS coding style

提高前端代码编码质量、编码规范、以及产品、UI、前端之间的配合流程规范可以明显的增强团队的协作效率以及减少错误的发生。本文站在一个前端工程师的角度来尝试总结一些产品开发中的种种规范。

前端编码规范(1)一般规范

  • 文件/资源命名

    1. 项目中,所有的文件名应该都遵循同一命名约定。 使用减号 来分隔资源名称
    2. 文件命名总是以 字母开头而不是数字 。以特殊字符开头命名的文件,一般都有特殊的含义与用处
    3. 资源的字母名称必须 全为小写 ,避免在某些对大小写字母敏感的操作系统中出现错误
    4. 还有一些情况下,需要对文件增加前后缀或特定的扩展名(比如 .min.js, .min.css)建议使用点分隔符来区分这些在文件名中带有清晰意义的元数据。
    5. class 必须单词全字母小写,单词间以 - 分隔
    • 不推荐:

      1
      2
      3
      4
      5
      MyScript.js
      myCamelCaseName.css
      i_love_underscores.html
      1001-scripts.js
      my-file-min.css
    • 推荐:

      1
      2
      3
      4
      5
      my-script.js
      my-camel-case-name.css
      i-love-underscores.html
      thousand-and-one-scripts.js
      my-file.min.css
  • 协议

    • 当引入图片或其他媒体文件,还有样式和脚本时,URLs 所指向的具体路径,不要指定协议部分(http:, https:)
    • 不推荐:<script src="http://cdn.com/foundation.min.js"></script>
    • 推荐:<script src="//cdn.com/foundation.min.js"></script>
  • 注释
    • 少写你的代码都干了些什么,而要写你的代码为什么要这么写,背后的考量是什么。当然也可以加入所思考问题或是解决方案的链接地址。
    • JSDoc 或 YUIDoc 就是用来写 JavaScript 注释用的工具
  • 代码检查
    • 对于 JavaScript,建议使用 JSLint 或 JSHint。

前端编码规范(2)HTML 规范

  1. 使用 HTML5 的文档类型申明: <!DOCTYPE html>
  2. HTML 验证:建议使用能通过标准规范验证的 HTML 代码,使用诸如 W3C HTML validator 这样的工具来进行检测
  3. 脚本加载:<script src="main.js"></script> 像这样的JS加载会一直阻塞 DOM 解析,直至它完全地加载和执行完毕。这会造成页面显示的延迟。特别是一些重量级的脚本,对用户体验来说那真是一个巨大的影响。异步加载脚本 可缓解这种性能影响。当然也可以将一些 JS 代码放在 </body> 之前

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    所有浏览器中,推荐:
    <html>
    <head>
    <link rel="stylesheet" href="main.css">
    </head>
    <body>
    <!-- body goes here -->

    <script src="main.js" async></script>
    </body>
    </html>
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    只在现代浏览器中,推荐:
    <html>
    <head>
    <link rel="stylesheet" href="main.css">
    <script src="main.js" async></script>
    </head>
    <body>
    <!-- body goes here -->
    </body>
    </html>
  4. 语义化:根据元素其被创造出来时的初始意义来使用它。打个比方,用 heading 元素来定义头部标题,p 元素来定义文字段落,用 a 元素来定义链接锚点,等等。有根据有目的地使用 HTML 元素,对于可访问性、代码重用、代码效率来说意义重大

  5. 多媒体回溯:对页面上的媒体而言,像图片、视频、canvas 动画等,要确保其有可替代的接入接口。图片文件我们可采用有意义的备选文本 alt ,保证每一张图片都有 alt 属性视频和音频文件我们可以为其加上说明文字或字幕
  6. type属性:鉴于 HTML5 中样式表与脚本上的 type 属性默认值就是 text/csstext/javascript,所以 type 属性一般是可以忽略掉的

    1
    2
    3
    不推荐:
    <link rel="stylesheet" href="main.css" type="text/css">
    <script src="main.js" type="text/javascript"></script>
    1
    2
    3
    推荐:
    <link rel="stylesheet" href="main.css">
    <script src="main.js"></script>
  7. HTML 引号:使用双引号(“”) 而不是单引号(‘)

    不推荐:<div class='news-article'></div>

    推荐: <div class="news-article"></div>

  8. 嵌套元素应当缩进一次
  9. 对于属性的定义,也是确保全部使用双引号,绝不要使用单引号
  10. 不要在自闭合(self-closing)元素(如:<br>)的尾部添加斜线 – HTML5 规范中明确说明这是可选的
  11. 不要省略可选的结束标签(closing tag)(例如,</li></body>
  12. 语言属性 : 根据 HTML5 规范:强烈建议为 html 根元素指定 lang 属性,从而为文档设置正确的语言。这将有助于语音合成工具确定其所应该采用的发音,有助于翻译工具确定其翻译时所应遵守的规则等等 <html lang="en-us"><!-- ... --></html>
  13. 字符编码 : 通过明确声明字符编码,能够确保浏览器快速并容易的判断页面内容的渲染方式。这样做的好处是,可以避免在 HTML 中使用字符实体标记(character entity),从而全部与文档编码一致(一般采用 UTF-8 编码)<head><meta charset="UTF-8"></head>
  14. 实用为王 : 尽量遵循 HTML 标准和语义,但是不要以牺牲实用性为代价。任何时候都要尽量使用最少的标签并保持最小的复杂度
  15. 属性顺序 : HTML 属性应当按照以下给出的顺序依次排列,确保代码的易读性

    1
    2
    3
    4
    5
    6
    7
    class
    id, name
    data-*
    src, for, type, href, value
    title, alt
    role, aria-*
    class 用于标识高度可复用组件,因此应该排在首位。id 用于标识具体组件,应当谨慎使用(例如,页面内的书签),因此排在第二位。
  16. 布尔(boolean)型属性 布尔型属性可以在声明时不赋值。XHTML 规范要求为其赋值,但是 HTML5 规范不需要。简单来说,就是不用赋值。推荐:

    1
    2
    3
    4
    5
    <input type="text" disabled>
    <input type="checkbox" value="1" checked>
    <select>
    <option value="1" selected>1</option>
    </select>
  17. 尽量减少标签的数量

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

Google JavaScript Style Guide

  • Google JavaScript Style Guide
  • Source file basics
    • 文件名必须全部小写,可以包含下划线(_)或破折号( - )(最好统一全部用破折号),但不得包含其他标点符号。 遵循你的项目使用的约定。 文件名的扩展名必须是.js
    • 常量命名应该使用全大写格式,并用下划线分割 遵守这条规则时需要注意的一点是,如果这个常量是一个函数,那么应该使用驼峰式命名法
    • 源文件以UTF-8编码
    • 除了每一行的终止符序列,ASCII水平空格符(0x20)是唯一一个可以出现在源文件中任意位置的空格字符。这也意味着,tab字符不应该被使用,以及被用来控制缩进。规范随后指出应该使用2个空格实现缩进,而不是4个空格带实现缩进
  • 由于ES6模块的语义尚不完全确定,所以暂时不要使用,比如export和import关键字。一旦它们的相关规范制定完成,那么请忽略这一条规则。
  • 所有控制结构(即if,else,for,do,while以及其他任何控制结构)都需要花括号,即使body只包含单个语句。 非空块的第一条语句必须从其自己的行开始
  • 使用const或let来声明所有局部变量。如果变量不需要被重新赋值,默认应该使用const。应该拒绝使用关键字var
  • 每一个变量声明都应该只对应着一个变量。不应该出现像let a = 1,b = 2;这样的语句
  • 在处理多行字符串时,模板字符串比复杂的拼接字符串要表现的更出色。${name}这样去插入变量
  • 只允许使用单引号包裹普通字符串,禁止使用双引号。如果字符串中包含单引号字符,应该使用模板字符串。
  • 在ES6中,有3种不同的for循环。尽管每一种有它的应用场景,但Google仍推荐使用for…of。真有趣,Google居然会特别指定一种for循环。虽然这很奇怪,但不影响我接受这一观点。
  • 不要使用eval语句
  • 箭头函数提供了一种简洁的语法,并且避免了一些关于this指向的问题。相比较与function关键字,开发者应该优先使用箭头函数来声明函数,尤其是声明嵌套函数。
  • 每个语句必须以分号结尾。不允许依赖于JS自动添加分号的功能。

以下是其他推荐的JS规范:

  • 全局命名空间污染与 IIFE :总是将代码包裹成一个 IIFE。用以创建独立隔绝的定义域。这一举措可防止全局命名空间被污染。不推荐写太多的全局变量:var a=1;alert(a); 推荐:(function(w,d){var a=1;alert(a);})(window,document); 它不仅避免了干扰,也使得内存在执行完后立即释放。所有脚本文件建议都从 IIFE 开始。立即执行函数有两种写法:1: (function(){})(); 2:(function(){}());
  • 严格模式 :可以考虑(不是必须)在你的脚本中启用严格模式,最好是在独立的 IIFE 中应用它。避免在你的脚本第一行使用它而导致你的所有脚本都启动了严格模式,这有可能会引发一些第三方类库的问题

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    //不推荐在全局开头使用严格模式
    'use strict';
    var a = 1;
    ... ...
    //推荐在IIFE中使用严格模式
    (function(w,d){
    'use strict';
    var a = 1;
    let b = 2;
    ... ...
    })(window,document);
  • 理解 JavaScript 的定义域和定义域提升 : 在 JavaScript 中变量和方法定义会自动提升到执行之前。JavaScript 只有 function 级的定义域,而无其他很多编程语言中的块定义域( let const 另说 ),所以使得你在某一 function 内的某语句和循环体中定义了一个变量,此变量可作用于整个 function 内,而不仅仅是在此语句或循环体中,因为它们的声明被 JavaScript 自动提升了

  • 提升声明 : 所有的变量以及方法,应当定义在 function 内的首行。只用一个 var 关键字声明,多个变量用逗号隔开,把赋值尽量写在变量申明中

  • 首选函数式风格 :函数式编程让你可以简化代码并缩减维护成本,因为它容易复用,又适当地解耦和更少的依赖

  • 避免修改内建对象的原型链
  • 适当使用 三元运算符 代替 if else

前端编码规范(4) CSS 规范

  1. idclass 命名要语义化,使用连字符作为分隔符
  2. 合理的避免使用 id : 始终考虑使用 class ,而不是 id,除非只使用一次,不要用 id 来应用样式
  3. CSS选择器构建 :尽量避免使用标签选择器
  4. CSS选择器尽可能的精确 : 不是通用的,应该尽可能使用直接子类选择器 >
  5. 缩写属性 : 使用缩写属性对于代码效率和可读性是有很有用的
  6. 0 和 单位 : 省略 0 值后面的单位。不要在 0 值后面使用单位。例如,用 margin: 0; 代替 margin: 0px;
  7. 十六进制表示法 : 在可能的情况下,使用3个字符的十六进制表示法(颜色值),始终使用小写的十六进制数字 例如,用 #fff 代替 #ffffff
  8. CSS声明顺序 : 最为最佳实践按照下面的先后顺序来写,不要漏掉每一个分号

    1
    2
    3
    4
    5
    6
    7
    8
    结构性属性:
    display
    position, left, top, right etc.
    overflow, float, clear etc.
    margin, padding
    表现性属性:
    background, border etc.
    font, text
  9. 属性名结束 属性名的冒号后使用一个空格。出于一致性的原因。如: color: white; 而不是 color:white;

  10. CSS引号 : 属性选择器或属性值用双引号(”),而不是单引号(’)括起来。URI值(url)不要使用引号。
  11. 对于属性值或颜色参数,省略小于 1 的小数前面的 0 (例如,.5 代替 0.5;-.5px 代替 -0.5px)
  12. 所有声明语句都应当以分号结尾。最后一条声明语句后面的分号是可选的,但是,如果省略这个分号,你的代码可能更易出错
  13. 为选择器分组时,将单独的选择器单独放在一行
  14. 为了代码的易读性,在每个声明块的左花括号前添加一个空格
  15. 声明块的右花括号应当单独成行。每条声明都应该独占一行
  16. 为选择器中的属性添加双引号,例如,input[type=”text”]。只有在某些情况下是可选的,但是,为了代码的一致性,建议都加上双引号
  17. 不要使用 @import
  18. 媒体查询(Media query)的位置 放在尽可能相关规则的附近
  19. 单行规则声明 : 对于只包含一条声明的样式,为了易读性和便于快速编辑,建议将语句放在同一行。对于带有多条声明的样式,还是应当将声明分为多行