前端代码规范及最佳实践 - Go语言中文社区

前端代码规范及最佳实践

本文来自 的 github repo
中文版 翻译： @老码农的自留地

概述

本文档包含了Isobar公司的创意技术部（前端工程）开发web应用的规范。现在我们把它开放给任何希望了解我们迭代过程最佳实践的人。

编写本文档的主要驱动力是两方面： 1) 代码一致性 以及 2) 最佳实践。 通过保持代码风格和传统的一致性，我们可以减少遗留系统维护的负担，并降低未来系统崩溃的风险。而通过遵照最佳实践，我们能确保优化的页面加载、性能以及可维护的代码。

{}

总体指导原则◊

前端开发核心思想◊

  1. 表现、内容和行为的分离
  2. 标记应该是结构良好、语义正确 以及 普遍合法 。
  3. Javascript应该起到渐进式增强用户体验的作用 。

总体原则◊

缩进◊

对于所有编程语言，我们要求缩进必须是软tab（用空格字符）。在你的文本编辑器里敲 Tab 应该等于 4个空格 。

可读性 vs 压缩◊

对于维护现有文件，我们认为可读性比节省文件大小更重要。大量空白和适当的ASCII艺术都是受鼓励的。任何开发者都不必故意去压缩HTML或CSS，也不必把Javascript代码最小化得面目全非。

我们会在服务器端或build过程中自动最小化并gzip压缩所有的静态客户端文件，例如CSS和JS。

{}

标记◊

任何网页的首要组件就是基于标签的HTML标记语言。超文本标记语言 (HTML) 曾有一段不堪回首的历史，但最近几年已经是 皇 上 回 宫 了。经过对它基于XML的XHTML变种的漫长试验之后，整个行业终于接受了HTML代表web的未来这一事实。

标记定义了文档的结构和纲要，并提供结构化的内容。除了最基本的概念（例如标题、段落和列表）之外，标记并不是用来定义页面上内容的外观和体验的。HTML的表现属性都已经被废弃了，有关样式的定义应该被包含在 样式表 中。

HTML5◊

HTML5 是HTML 和 XHTML 的新版本。 在 HTML5 草案 的规范中定义了可以用 HTML 和 XML编写的单一的语言，意在解决在之前HTML的迭代中发现的一些问题并满足web应用的需求，这是以前HTML没有充分覆盖到的领域（来源 ） 。

在合适的时候，我们会使用HTML5 Doctype 和 HTML5 特性。

我们会对照 W3C 校验器 测试我们的标记，以确保标记是结构良好的。我们的目标并不是100%的合法代码，但是校验肯定对于编写可维护的站点以及调试代码都大有帮助。 Isobar公司不保证代码都是100%合法，而是确信跨浏览器体验会相当一致 。

模板◊

对HTML5文件，我们使用 H5BP 针对我们自己项目需求修改的一个分支。 你也可以从这里Fork H5BP。

Doctype◊

标记中必须总是使用合适的Doctype来指示浏览器触发标准模式. 永远要避免Quirks模式。

HTML5特别好的一个方面就是它简化了Doctype需要的代码。无意义的属性被弃用了，DOCTYPE 声明也被显著地简化了。另外，也无需再用 CDATA 对内联JavaScript代码进行转义，而这在此之前为了让XHTML符合XML的严密性是必需的。

HTML5 Doctype
1. <!DOCTYPE html>

字符编码◊

所有标记必须通过UTF-8编码传递，因为这种编码方式是对国际化最友好的。必须在HTTP的header和HTML文档的head部分都指定这种编码。

设定字符编码是通过 <meta> 标签进行。

1. <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />

如果是HTML5，则只需要写：

1. <meta charset="utf-8">

标记的总体原则◊

下面是编写HTML标记的总体原则。提醒大家一点，在创建的HTML文档里总是要使用能够代表内容语义的标记。

    • 段落分隔符要使用实际对应的<p>元素，而不是用多个<br>标签。
    • 在合适的条件下，充分利用<dl> （定义列表）和<blockquote> 标签。
    • 列表中的条目必须总是放置于<ul>、<ol>或<dl> 中，永远不要用一组 <div>或<p> 来表示。
    • 给每个表单里的字段加上 <label> 标签，其中的 for 属性必须和对应的输入字段对应，这样用户就可以点击标签。同理，给标签加上 cursor:pointer; 样式也是明智的做法。 讨论 1
      讨论 2
    • 不用使用输入字段中的 size 属性。该属性是和输入字段里文本的 font-size 相关的。应该使用CSS宽度。
    • 在某些闭合的 </div> 标签旁边加上一段html注释，说明这里闭合的是什么元素。这在有大量嵌套和缩进的情况下会很有用。
    • 不要把表格用于页面布局。
    • 在合适的条件下，利用 microformats 和/或者 Microdata ，具体说是 hCard 和 adr。
    • 在合适的条件下，利用 <thead>、<tbody>和<th>标签 (以及Scope属性）。
具备恰当语法结构(THEAD,TBODY,TH [scope])的 Table 标记
01. <table summary="This is a chart of year-end returns for 2005.">
02.     <thead>
03.         <tr>
04.             <th scope="col">Table header 1</th>
05.             <th scope="col">Table header 2</th>
06.         </tr>
07.     </thead>
08.     <tbody>
09.         <tr>
10.             <td>Table data 1</td>
11.             <td>Table data 2</td>
12.         </tr>
13.     </tbody>
14. </table>
  • 对于页眉和标题，永远使用首字母大写格式。不要在标记中使用全部大写或小写的标题，而是应用CSS属性 text-transform:uppercase/lowercase 。

属性加引号◊

在HTML5规范里并没有严格要求属性值两边加引号。但考虑到一些属性可以接受空白值，为了保持一致性，我们要求所有属性值必须加上引号。

1. <p class="line note" data-attribute="106">This is my paragraph of special text.</p>
{}

CSS◊

网页的第二个组件就是在层叠样式表（CSS）中包含的表现信息。Web浏览器成功实现CSS后，整整一代web开发者对他们网站的外观和体验拥有了全部的控制权。

正如网页信息在语义方面由 HTML 标记 描述， CSS 从表现方面则是通过对视觉属性的定义来描述网页。 CSS 的强大之处在于，这些属性可以混合并通过各种标示符匹配，它可以通过样式规则的分层（”层叠“）来控制页面的布局和视觉特征。

编码总体原则◊

  • 从外部文件加载CSS，尽可能减少文件数。加载标签必须放在文件的 HEAD 部分。
  • 用 LINK 标签加载，永远不要用@import。
    加载样式表
    1. <link rel="stylesheet" type="text/css" href="myStylesheet.css" />
    不要用内联式样式
    1. <p style="font-size: 12px; color: #FFFFFF">This is poor form, I say</p>
  • 不要在文件中用内联式引入的样式，不管它是定义在样式标签里还是直接定义在元素上。这样会很难追踪样式规则。
  • 使用 normalize.css 让渲染效果在不同浏览器中更一致。
  • 使用类似 YUI fonts.css 的字体规格化文件。
  • 定义样式的时候，对样式在页面只出现一次的元素用id，其他的用class。
  • 理解 层叠和选择器的明确度 ，这样你就可以写出非常简洁且高效的代码。
  • 编写性能优化的选择器。尽可能避免使用开销大的CSS选择器。例如，避免 * 通配符选择器，也不要叠加限定条件到 ID 选择器（例如 div#myid）或 class 选择器（例如 table.results）上。这对于速度至上并包含了成千上万个DOM元素的web应用来说尤为重要。更多相关内容请参阅 MDN 上的这篇 《编写高效CSS》。

CSS盒子模型◊

深入学习和理解CSS及基于浏览器的盒子模型，对于掌握CSS布局的基础是非常必要的。

CSS Box Model3D CSS 盒子模型示意图， 由 Jon Hicks 绘制。

CSS 校验◊

我们一般不用 W3C 校验器。

CSS 格式◊

最低要求：选择器单独占一行，每个属性占一行。属性声明要有缩进。

作为提高的要求，关联或孩子样式要增加2-4个空格的缩进。这样有利于分层查看和组织，产生（对某些人来说）可读性更好的样式表。

另外，在给一个样式指定多个选择器的时候，把每个选择器单独放一行是个好主意。这样可以避免一行变得太长，也能提高可读性及版本控制流程。

01. .post-list li a{
02.     color:#A8A8A8;
03. }
04.     .post-list li a:hover{
05.         color:#000;
06.         text-decoration:none;
07.     }
08.     .post-list li .author a,
09.     .post-list li .author a:hover{
10.          color:#F30;
11.          text-transform:uppercase;
12.     }

在多个开发者协作环境下，避免用单行CSS格式，因为这样会给版本控制带来问题。

字母排序◊

如果你对性能情有独钟， 对CSS属性进行字母排序有利于在GZIP压缩中识别大量可重复的特征。

Classes vs. IDs◊

对于所用的样式只出现一次的元素，给它设一个id属性。这个属性只会应用于该元素，不会用到其他地方。Class属性则可以用到多个具有相同样式属性的元素上。具有相同外观和表现的元素可以具有相同的class名。

1. <ul id="categories">
2.     <li class="item">Category 1</li>
3.     <li class="item">Category 2</li>
4.     <li class="item">Category 3</li>
5. </ul>

选择器命名的惯例◊

无论是 ID 还是 class，对任何东西最好总是根据 它是什么 而不是 它看上去是什么样子 来命名。 比如一个页面上的特别提示的 class 名是 bigBlueText （大蓝字），可它的样式早就被改成红色小字体，这个名字就没意义了。使用更聪明的惯例如 noteText （提示文字）就好多了，因为即使视觉样式改变了，它也还是管用的。

选择器◊

CSS3 选择器 规格引入了一整套对于更好地选择元素极其有用的 CSS 选择器。

伪类◊

伪类 使你能动态地修饰网页内容的样式。有些伪类从CSS1 （:visited, :hover等） 和 CSS2 （:first-child, :lang）那时候开始就有了。CSS3又往列表里加入了16个新的伪类，这些伪类对于动态地修饰网页内容的样式特别有用。 学习如何深度使用伪类。

组合及属性选择器◊

组合选择器 提供了为特定元素选择其后代元素、孩子元素或兄弟元素的快捷方式。

属性选择器 适用于具有特定属性 和/或 特定值的元素。正则表达式的知识对属性选择大有帮助。

明确度◊

浏览器会通过 计算选择器的明确度 来决定应用哪个CSS规则。如果两个选择器都适用于同样的元素，具有更高明确度的那个会胜出。

ID 选择器比属性选择器明确度高，class 选择器比任何数量的元素选择器明确度高。尽量使用 ID 选择器来提高明确度。有时候我们可能会想方设法给一个元素应用一条CSS规则，但用尽方法也不能如愿。这种情况有可能是因为我们使用的选择器比另外一个的明确度低，所以明确度高的另一个选择器里的属性就比我们想应用的选择器优先了。这种情况在更大或更复杂的样式表里更为常见。在小一些的项目里，通常这不是大问题。

计算明确度◊

当你在一个很大很复杂的样式表上干活的时候，知道如何计算选择器的明确度会有很大帮助，会节约你的时间，并让你的选择器更有效率。

明确度的计算方式是对你的CSS的各种组件计数，并用 (a,b,c,d) 格式表达出来。

  • 元素，伪元素: d = 1 – (0,0,0,1)
  • 类，伪类，属性: c = 1 – (0,0,1,0)
  • Id: b = 1 – (0,1,0,0)
  • 内联样式: a = 1 – (1,0,0,0)

不过，也许使用现成的明确度计算器更好一些。

使用 !important 会覆盖掉所有的明确度，不管它有多高。因此我们倾向于避免使用它。大部分时候是没必要用它的。即使你需要覆盖某个你访问不到的样式表里的选择器，往往也会有其他的办法去覆盖。尽可能避免使用它。

像素 vs. Em◊

我们使用 px 作为定义 font size 的度量单位，因为它能提供对文本的绝对控制。我们知道为字体大小使用 em 单位一度很流行，这样可以解决 IE6 无法改变基于像素的文本大小的问题。不过，现在所有的主流浏览器（包括 IE7 和 IE8）都支持基于像素单位的文本大小 和/或 整页缩放。既然 IE6 被广泛认为已废弃，用像素定义文本尺寸更好。另外，无单位的 line-height 也应该优先考虑，因为它不会从父元素继承一个百分比值，而是基于 font-size 的一个乘数。

正确
1. #selector {
2.     font-size: 13px;
3.     line-height: 1.5;  /*  13 * 1.5 = 19.5 ~ Rounds to 20px. */
4. }
不正确
1. /*  Equivalent to 13px font-size and 20px line-height, but only if the browser default text size is 16px. */
2. #selector {
3.     font-size: 0.813em;
4.     line-height: 1.25em;
5. }

IE Bugs◊

不可避免地，当所有其他浏览器看起来都正常工作的时候，各种版本的IE浏览器就会冒出一些莫名其妙的bug，让部署一拖再拖。虽然我们鼓励排除问题，产出无需打补丁就能在所有浏览器上运行的代码，有时候为了在样式表中使用CSS钩子，还是有必要用到CSS if IE 条件注释。从 paulirish.com 了解更多信息。

修复 IE
1. <!--[if lt IE 7 ]> <body class="ie6"> <![endif]-->
2. <!--[if IE 7 ]>    <body class="ie7"> <![endif]-->
3. <!--[if IE 8 ]>    <body class="ie8"> <![endif]-->
4. <!--[if IE 9 ]>    <body class="ie9"> <![endif]-->
5. <!--[if !IE]><!--> <body> <!--<![endif]-->
1. .box { float: left; margin-left: 20px; }
2. .ie6 .box { margin-left: 10px; }

如果你在用HTML5（以及 HTML5 Boilerplate）， 我们推荐使用 Modernizer JavaScript库和下列模式：

1. <!--[if lt IE 7]> <html class="no-js ie ie6" lang="en"> <![endif]-->
2. <!--[if IE 7]>    <html class="no-js ie ie7" lang="en"> <![endif]-->
3. <!--[if IE 8]>    <html class="no-js ie8" lang="en"> <![endif]-->
4. <!--[if IE 9]>    <html class="no-js ie9" lang="en"> <![endif]-->
5. <!--[if gt IE 9]><!--><html class="no-js" lang="en"><!--<![endif]-->

速记格式◊

一般情况下要优先使用CSS速记格式，一是因为它的简洁，二是用它也可以扩充已有的值，例如margin和padding的情况。 开发者必须注意TRBL 缩写，它表示元素的各边按顺时针方向定义的顺序：上、右、下、左。如果bottom没有定义，它就会从top继承值。同理，如果left未定义，它从right继承值。如果只有top的值有定义，所有的边都会继承那一个值。

下面是关于减少样式表代码冗余和使用CSS速记格式的更多内容：

图片◊

  • 对于（用于背景的）重复图片，要使用 比 1×1 像素大的图片
  • 永远不要用空白图片。
  • 多使用 CSS精灵（sprites）。它会使悬停状态更简单，改善页面加载速度，并减少二氧化碳的排放。
  • 一般情况下，所有的图片都应该切成带透明背景（PNG8），并裁减成紧密贴合图片外边框。
    • 不过，logo必须总是带有背景遮片，并在裁减内容之外留出内边框。

颜色管理◊

  • 确认团队所有成员都有一致的颜色管理设置。
    • 任意两台显示器显示的颜色很可能会有所不同，但必须使用sRGB颜色作为缺省配置。
    • 当你在Photoshop打开文件时，要注意颜色配置警告，当Photoshop建议把图片转换到另一个配置时，要通知其他团队成员。
  • 永远不要把颜色配置嵌入到图片里。
    • 当你从Photoshop保存图片时，务必去掉”Embed Color Profile”选项的勾选。

通用的文本和字体样式◊

标题◊

  • 要给 h1-h6 标题 — 包括作为链接的标题 — 定义缺省样式。在你的CSS文档顶部定义它们，在必要时修改它们以保持整个站点的一致性。
  • 标题必须有层次，能表明从大到小不同级别的重要性，h1具有最大的字体大小。
  • SEO：要大致地了解页面的层次组织和阅读效果，在开发者工具里关闭CSS效果，你会看到一个基于文字的视图，包括所有的 h1-h6 ， strong， em 等标签。

链接◊

  • 必须定义链接的缺省样式，样式要和主要的文字样式不同，载悬停状态下也要有不同的样式。
  • 当给链接加下划线样式时，使用 border-bottom 并用 text-decoration: none; 加点内边框。这样看起来更好一些。
{}

JavaScript◊

JavaScript 是网页的第三个主要部件。在网页上适当地应用JavaScript 代码，通过绑定事件和控制整体行为层，能够增强整体的用户和基于浏览器的体验。

随着功能强劲的新浏览器撑起基于浏览器的完整web应用，JavaScript 在近年的流行度爆棚。另外，对Javascript的细致运用为全面操控另外两个部件 — HTML 标记 和 CSS — 提供了手段。现在，在无需刷新整个页面的情况下，页面结构和页面视觉样式都可以被实时操控。

JavaScript库◊

我们开发新应用主要会用到 jQuery，不过我们对原生 JavaScript 和所有现代 javascript 库也具有专业经验。

编码总体原则◊

  • 99%的代码必须封装在外部Javascript文件中。这些文件必须在 BODY 标签的尾部引入，让页面的性能最大化。
  • 不要依赖于 user-agent 字符串。进行适当的特性检测. （更多信息参见 深入 HTML5： 检测 和 jQuery 支持文档）
  • 不要使用 document.write()。
  • 所有布尔变量的命名必须用 “is” 开头
    对正条件的测试
    1. isValid = (test.value >= 4 && test.success);
  • 给变量和函数的命名要有逻辑意义：例如： popUpWindowForAd 就比 myWindow 好多了。
  • 不要人为缩短命名到最小。除了传统的 for 循环中的计数器 i 等简化的情况，变量命名必须长到有明确意义。
  • 文档必须遵循 NaturalDocs 结构。
  • 常量或配置变量（例如动画持续时间等）必须放在文件的顶部。
  • 尽力编写可通用化的函数，让它接受参数并返回值。这样有利于充分的代码重用，而且一旦与引入及外部脚本配合起来，能在脚本需要修改时减少开销。例如，相比硬编码一个带有窗口大小、选项和url的弹出式窗口，不如编写一个接受大小、url和选项作为变量的函数。
  • 给代码添加注释！这会有利于减少在调试Javascript函数上花费的时间。
  • 不要把时间浪费在用 <!-- --> 给你的内联Javascript加注释上，除非你还在关注 Netscape 4。 :)
  • 把你的代码组织成一套 对象常量/单例，按照 模块化模式，或做成 带构造器的对象。
  • 最小化全局变量 – 你创建的全局变量越少越好。一般来说，用于你的应用命名空间，1会是个好的数字。
    在描述任何全局变量的时候要明确指认。
    1. window.globalVar = { ... }

留空◊

总的来说，使用留空应该遵循源远流长的英语阅读惯例。 例如，每个逗号和冒号（以及适用的分号）后面要空一格，但在括号内部的左侧和右侧都不要加空格。另外，大括号应该总是和他们前面的参数出现在同一行。

来看看下面的 JavaScript for循环的例子…

正确
1. for (var i = 0, j = arr.length; i < j; i++) {
2.     // Do something.
3. }
不正确
1. for ( var i = 0, j = arr.length; i < j; i++ )
2. {
3.     // Do something.
4. }
也不正确
1. for(var i=0,j=arr.length;i<j;i++){
2.     // Do something.
3. }

plugins.js 和 script.js◊

从 H5BP 开始我们看到了两个文件， plugins.js 和 script.js。本节概述这两个文件的基本用法。

plugins.js◊

Plugins.js 的用处是存放网站的所有插件代码。相比链接到很多不同的文件，我们可以把插件代码统一放到这个文件里，从而改善性能。这种用法会有也应该有例外。例如，一个超级大的插件，又只是用在一个很少被访问到的页面上，放在单独的一个下载链接里就会更好，这样只会在目标页面被打开的时候才会被访问。不过，大部分情况下，直接把所有插件的最小化版本粘贴到这里以便访问是靠谱的。

下面就是一个样例文件，包括一个小目录。它可以作为所用到插件的随身指南，包括文档URL，使用它们的思路，诸如此类。

01. /* PLUGIN DIRECTORY
02. 本文件中出现的插件 [按出场顺序排序]
03.  
04.        1.) Animate Background Position - http://plugins.jquery.com/project/backgroundPosition-Effect
05.        2.) jQuery Easing Plugin - http://gsgd.co.uk/sandbox/jquery/easing/
06.        3.) jQuery Ajax Form plugin - http://jquery.malsup.com/form/#download           
07.        4.) jQuery validation plugin (form validation) - http://docs.jquery.com/Plugins/Validation
08.            -password strength
09.        5.) Styled Selects (lightweight) - http://code.google.com/p/lnet/wiki/jQueryStyledSelectOverview
10. */
11.  
12. /**
13. * 1.) Animate Background Position - http://plugins.jquery.com/project/backgroundPosition-Effect
14. * @author Alexander Farkas
15. * v. 1.21
16. */
17. (function($) {
18.    if(!document.defaultView || !document.defaultView.getComputedStyle){ // IE6-IE8
19.    //SNIPPED
20.    };
21. })(jQuery);
22.  
23.  
24. /**
25. * 2.) jQuery Easing Plugin (we're not using jQuery UI as of yet) - http://gsgd.co.uk/sandbox/jquery/easing/
26. 版权声明：本文来源CSDN，感谢博主原创文章，遵循 CC 4.0 by-sa 版权协议，转载请附上原文出处链接和本声明。
原文链接：https://blog.csdn.net/u014272528/article/details/40618439
站方申明：本站部分内容来自社区用户分享，若涉及侵权，请联系站方删除。
  • 发表于 2021-05-31 04:31:22
  • 阅读 ( 787 )
  • 分类：前端

你可能感兴趣的文章

精选的优质文章

0 条评论

请先 登录 后评论

官方社群

GO教程

推荐文章

猜你喜欢

随便看看

来源51CTO

如果觉得我的文章对您有用，请随意打赏。你的支持将鼓励我继续创作！