Web 前端程式碼規格

最後更新時間：2017-06-25

原文連結：

此項目用於記錄規格的、高可維護性的前端程式碼，這是透過分析Github 眾多前端程式庫，總結出來的前端程式碼書寫規格。

index.shtml 引導頁&首頁
#main.shtml 首頁
download.shtml下載頁面
act.html 活動清單頁面
#video.html 影片
cdkey. html CDKEY頁面
base.css 基本樣式
#layout.css 框架佈局
module .css 模組樣式
global.css 全域樣式
font.css 字型樣式
index.css 首頁樣式
link.css 連結樣式
print.css 列印樣式

HTML 規格

語法

使用四個空格的縮進，這是保證程式碼在各種環境下顯示一致的唯一方式。

巢狀的節點應該要縮排（四個空格）。

在屬性上，使用雙引號，不要使用單引號。

不要在自動閉合標籤結尾處使用斜線 - HTML5 規範指出他們是可選的。

不要忽略可選的關閉標籤（例如，和）。

![](images/logo.png)

登入後複製

HTML5 doctype

在每個 HTML 頁面開頭使用這個簡單地 doctype 來啟用標準模式，使其每個瀏覽器中盡可能一致的展現。

雖然doctype不區分大小寫，但是按照慣例，doctype大寫

<!DOCTYPE html>

登入後複製

語言屬性

<html lang="en"></html>

登入後複製

字元編碼

透過明確聲明字元編碼，能夠確保瀏覽器快速且容易的判斷頁面內容的渲染方式。這樣

做的好處是，可以避免在 HTML 中使用字元實體標記（character entity），因此全部與
文件編碼一致（一般採用 UTF-8 編碼）。

<meta charset="UTF-8">

登入後複製

IE 相容模式

IE 支援透過特定的標籤來決定繪製目前頁面所應該採用的 IE 版本。除非有強烈

的特殊需求，否則最好是設定為 edge mode，從而通知 IE 採用其所支援的最新的模
式。

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

登入後複製

響應式

<meta name="viewport" content="width=device-width, initial-scale=1">

登入後複製

引入CSS 和JavaScript

#根據HTML5 規格, 通常在引入CSS 和JavaScript 時不需要指明type，因為text/css 和text/javascript分別是他們的預設值。

<!-- External CSS --><link rel="stylesheet" href="code-guide.css?1.1.11"><!-- In-document CSS --><style>/* ... */</style><!-- JavaScript --><script src="code-guide.js?1.1.11"></script>

登入後複製

實用高於完美

盡量遵循 HTML 標準和語義，但不應該以浪費實用性作為代價。任何時候都要用盡量小的複雜度和盡量少的標籤來解決問題。

減少標籤數量

在編寫 HTML 程式碼時，需要盡量避免多餘的父節點。很多時候，需要透過迭代和重構來使 HTML 變得更少。參考下面的範例:

<!-- Not so great --><span class="avatar">
    ![](...)</span><!-- Better -->
![](...)

登入後複製

屬性順序

HTML 屬性應該按照特定的順序出現以確保易讀性。

class
id
name
# #data-*
src, for, type, href, value , max-length, max, min, pattern
placeholder, title , alt
aria-*, role
#required, readonly, disabled

class 是為高可重複使用組件設計的，理論上應處於第一位。 id 更具體而且應該盡量少使用（例如, 頁內書籤），所以他們處在第二位。

Boolean 屬性

Boolean 屬性指不需要宣告取值的屬性。 XHTML 需要每個屬性宣告取值，但 HTML5 並不需要。 ###

一个元素中 Boolean 属性的存在表示取值 true，不存在则表示取值 false。

简而言之，不要为 Boolean 属性添加取值。

<input type="text" disabled>

登入後複製

JavaScript 生成标签

在 JavaScript 文件中生成标签让内容变得更难查找，更难编辑，性能更差。应该尽量避免这种情况的出现。

CSS 规范

语法

使用四个空格的缩进，这是保证代码在各种环境下显示一致的唯一方式。

使用组合选择器时，保持每个独立的选择器占用一行。

为了代码的易读性，在每个声明的左括号前增加一个空格。

声明块的右括号应该另起一行。

每条声明 : 后应该插入一个空格。

每条声明应该只占用一行来保证错误报告更加准确。

所有声明应该以分号结尾。虽然最后一条声明后的分号是可选的，但是如果没有他，你的代码会更容易出错。

逗号分隔的取值，都应该在逗号之后增加一个空格。

不要在颜色值 rgb() rgba() hsl() hsla()和 rect() 中增加空格，并且不要带有取值前面不必要的 0 (比如，使用 .5 替代 0.5)。

所有的十六进制值都应该使用小写字母，例如 #fff。因为小写字母有更多样的外形，在浏览文档时，他们能够更轻松的被区分开来。

尽可能使用短的十六进制数值，例如使用 #fff 替代 #ffffff。

为选择器中的属性取值添加引号，例如 input[type="text"]。他们只在某些情况下可有可无，所以都使用引号可以增加一致性。

不要为 0 指明单位，比如使用 margin: 0; 而不是 margin: 0px;。

/* Bad CSS */.selector, .selector-secondary, .selector[type=text] {margin: 0px 0px 15px;background-color: rgba(0, 0, 0, 0.5);box-shadow: 0 1px 2px #CCC, inset 0 1px 0 #FFFFFF
}/* Good CSS */.selector,.selector-secondary,.selector[type="text"] {margin-bottom: 15px;background-color: rgba(0,0,0,.5);box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff;
}

登入後複製

声明顺序

相关的属性声明应该以下面的顺序分组处理：

Positioning
Box model 盒模型
Typographic 排版
Visual 外观

Positioning 处在第一位，因为他可以使一个元素脱离正常文本流，并且覆盖盒模型相关的样式。盒模型紧跟其后，因为他决定了一个组件的大小和位置。

其他属性只在组件内部起作用或者不会对前面两种情况的结果产生影响，所以他们排在后面。

.declaration-order {/* Positioning */position: absolute;top: 0;right: 0;bottom: 0;left: 0;z-index: 100;/* Box-model */display: block;float: right;width: 100px;height: 100px;/* Typography */font: normal 13px "Helvetica Neue", sans-serif;line-height: 1.5;color: #333;text-align: center;/* Visual */background-color: #f5f5f5;border: 1px solid #e5e5e5;border-radius: 3px;/* Misc */opacity: 1;
}

登入後複製

Don't use @import

与<link>相比，@import较慢，增加额外的页面请求，并可能导致其他不可预见的问题。

<!-- Use link elements --><link rel="stylesheet" href="core.css?1.1.11"><!-- Avoid @imports --><style>@import url("more.css?1.1.11");</style>

登入後複製

媒体查询位置

尽量将媒体查询的位置靠近他们相关的规则。不要将他们一起放到一个独立的样式文件中，或者丢在文档的最底部。这样做只会让大家以后更容易忘记他们。这里是一个典型的案例。

.element { ... }.element-avatar { ... }.element-selected { ... }

@media (min-width: 480px) {.element { ...}.element-avatar { ... }.element-selected { ... }
}

登入後複製

前缀属性

当使用厂商前缀属性时，通过缩进使取值垂直对齐以便多行编辑。

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

登入後複製

单条声明的声明块

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

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

.span1 { width: 60px; }.span2 { width: 140px; }.span3 { width: 220px; }

登入後複製

属性简写

尽量不使用属性简写的方式，属性简写需要你必须显式设置所有取值。常见的属性简写滥用包括:

padding
margin
font
background
-border
-border-radius

大多数情况下，我们并不需要设置属性简写中包含的所有值。例如，HTML 头部只设置上下的 margin，所以如果需要，只设置这两个值。过度使用属性简写往往会导致更混乱的代码，其中包含不必要的重写和意想不到的副作用。

/* Bad example */.element {margin: 0 0 10px;background: red;background: url("image.jpg");border-radius: 3px 3px 0 0;
}/* Good example */.element {margin-bottom: 10px;background-color: red;background-image: url("image.jpg");border-top-left-radius: 3px;border-top-right-radius: 3px;
}

登入後複製

Less 和 Sass 中的嵌套

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

// Without nesting.table > thead > tr > th { … }.table > thead > tr > td { … }// With nesting.table > thead > tr {
    > th { … }
    > td { … }
}

登入後複製

代码注释

代码是由人来编写和维护的。保证你的代码是描述性的，包含好的注释，并且容易被他人理解。好的代码注释传达上下文和目标。不要简单地重申组件或者 class 名称。

class 命名

保持 class 命名为全小写，可以使用短划线（不要使用下划线和 camelCase 命名）。短划线应该作为相关类的自然间断。(例如，.btn 和 .btn-danger)。

避免过度使用简写。.btn 可以很好地描述 button，但是 .s 不能代表任何元素。

class 的命名应该尽量短，也要尽量明确。

使用有意义的名称；使用结构化或者作用目标相关，而不是抽象的名称。

命名时使用最近的父节点或者父 class 作为前缀。

使用 .js-* 来表示行为(相对于样式)，但是不要在 CSS 中包含这些 class。

选择器

使用 class 而不是通用元素标签来优化渲染性能。

避免在经常出现的组件中使用一些属性选择器 (例如，[class^="..."])。浏览器性能会受到这些情况的影响。

减少选择器的长度，每个组合选择器选择器的条目应该尽量控制在 3 个以内。

只在必要的情况下使用后代选择器 (例如，没有使用带前缀 classes 的情况).

代码组织

以组件为单位组织代码。

制定一个一致的注释层级结构。

使用一致的空白来分割代码块，这样做在查看大的文档时更有优势。

当使用多个 CSS 文件时，通过组件而不是页面来区分他们。页面会被重新排列，而组件移动就可以了。

编辑器配置

根据以下的设置来配置你的编辑器，将这些设置应用到项目的 .editorconfig 文件，来避免常见的代码不一致和丑陋的 diffs。

使用四个空格的缩进。
在保存时删除尾部的空白字符。
设置文件编码为 UTF-8。
在文件结尾添加一个空白行。

JS 规范

语法

使用四个空格的缩进，这是保证代码在各种环境下显示一致的唯一方式。

声明之后一律以分号结束，不可以省略

完全避免 == != 的使用，用严格比较条件 === !==

eval 非特殊情况，禁用！！！

with 非特殊情况，禁用！！！

单行长度，理论上不要超过80列，不过如果编辑器开启"自动换行"的话可以不考虑单行长度

接上一条，如果需要换行，存在操作符的情况，一定在操作符后换行，然后换的行缩进4个空格

这里要注意，如果是多次换行的话就没有必要继续缩进了，比如说下面这种就是最佳格式。

if (typeof qqfind === "undefined" ||
    typeof qqfind.cdnrejected === "undefined" ||
    qqfind.cdnrejected !== true) {url = "http://pub.idqqimg.com/qqfind/js/location4.js?1.1.11";
} else {url = "http://find.qq.com/js/location4.js?1.1.11";
}

登入後複製

空行

方法之间加

单行或多行注释前加

逻辑块之间加空行增加可读性

变量命名

标准变量采用驼峰标识

使用的ID的地方一定全大写

使用的URL的地方一定全大写, 比如说 reportURL

涉及Android的，一律大写第一个字母

涉及iOS的，一律小写第一个，大写后两个字母

常量采用大写字母，下划线连接的方式

构造函数，大写第一个字母

var thisIsMyName;var goodID;var AndroidVersion;var iOSVersion;var MAX_COUNT = 10;function Person(name) {this.name = name
}

登入後複製

字符常量

一般情况下统一使用单引号

null的使用场景

初始化可能以后分配对象值的变量

与一个可能或可能没有对象值的初始化变量进行比较

传入一个预期对象的函数

从预期对象的函数返回

不适合null的使用场景

不要使用null来测试是否提供参数

不要测试值为null的未初始化变量

undefined使用场景

永远不要直接使用undefined进行变量判断

使用字符串 "undefined" 对变量进行判断

// Badvar person;console.log(person === undefined);    //true// Goodconsole.log(typeof person);    // "undefined"

登入後複製

对象字面量

// Badvar team = new Team();
team.title = "AlloyTeam";
team.count = 25;// Goodvar team = {
    title: "AlloyTeam",count: 25
};

登入後複製

数组声明

// Badvar colors = new Array("red", "green", "blue");var numbers = new Array(1, 2, 3, 4);// Goodvar colors = [ "red", "green", "blue" ];var numbers = [ 1, 2, 3, 4 ];

登入後複製

单行注释

双斜线后，必须跟注释内容保留一个空格

与下一行代码缩进保持一致

可位于一个代码行的末尾，双斜线距离分号四个空格

// Goodif (condition) {// if you made it here, then all security checks passed
    allowed();
}var zhangsan = "zhangsan";    // 双斜线距离分号四个空格，双斜线后始终保留一个空格

登入後複製

多行注释格式

最少三行

前边留空一行

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

登入後複製

何时使用多行注释格式

难于理解的代码段

可能存在错误的代码段

浏览器特殊的HACK代码

业务逻辑强相关的代码

想吐槽的产品逻辑, 合作同事

文档注释

各类标签 @param @method 等参考

用于：方法、构造函数、对象

/**
 * here boy, look here , here is girl
 * @method lookGril
 * @param {Object} balabalabala
 * @return {Object} balabalabala
 */

登入後複製

括号对齐

标准示例括号前后有空格，花括号起始不另换行，结尾新起一行

花括号必须要，即使内容只有一行

涉及 if for while do...while try...catch...finally 的地方都必须使用花括号，即使内容只有一行

if else 前后留有空格

if (condition) {doSomething();
} else {doSomethingElse();
}

登入後複製

switch

switch和括号之间有空格，case需要缩进，break之后跟下一个case中间留一个空白行

花括号必须要，即使内容只有一行。

switch 的 falling through 一定要有注释特别说明，no default 的情况也需要注释特别说明况

switch (condition) {case "first":// codebreak;case "second":// codebreak;default:// code
}

登入後複製

for

普通for循环, 分号后留有一个空格，判断条件等内的操作符两边不留空格

前置条件如果有多个，逗号后留一个空格

for-in 一定要有 hasOwnProperty 的判断，否则 JSLint 或者 JSHint 都会有一个 warn

for (i=0, len=values.length; i<len; i++) {
    process(values[i]);
}var prop;for (prop in object) {// 注意这里一定要有 hasOwnProperty 的判断， 否则 JSLint 或者 JSHint 都会有一个 warn ！if (object.hasOwnProperty(prop)) {
        console.log("Property name is " + prop);
        console.log("Property value is " + object[prop]);
    }
}

登入後複製

变量声明

所有函数内变量声明放在函数内头部，只使用一个 var(多了JSLint报错)，一个变量一行，在行末跟注释，注释啊，注释啊，亲

函数声明

一定先声明再使用，不要利用 JavaScript engine的变量提升特性, 违反了这个规则 JSLint 和 JSHint都会报 warn

function declaration 和 function expression 的不同，function expression 的（）前后必须有空格，而function declaration 在有函数名的时候不需要空格，没有函数名的时候需要空格。

函数调用括号前后不需要空格

立即执行函数的写法, 最外层必须包一层括号

"use strict" 决不允许全局使用，必须放在函数的第一行，可以用自执行函数包含大的代码段, 如果 "use strict" 在函数外使用， JSLint 和 JSHint 均会报错

function doSomething(item) {// do something
}var doSomething = function (item) {// do something
}// Good
doSomething(item);// Bad: Looks like a block statement
doSomething (item);// Good
(function() {    "use strict";function doSomething() {// code
    }
})();

登入後複製

以上是Web 前端程式碼規範的詳細內容。更多資訊請關注PHP中文網其他相關文章！