Web フロントエンドコード仕様

最終更新日: 2017-06-25

元記事リンク:

このプロジェクトは、多くのフロントエンドを分析することで実現される、標準化された保守性の高いフロントエンドコードを記録するために使用されます。 Github のコードライブラリ、フロントエンドコード記述仕様をまとめたもの。そのまま受け取ってください。

ありがとうございます

@materliu: https://materliu.github.io/code-guide
@tguide:
黄金律
同じプロジェクトに何人で取り組んでも、コードのすべての行が同じ人によって書かれたように見えるようにしてください。

プロジェクト名はすべて小文字で、ダッシュで区切ることは禁止されています。例: my-project-name

ファイルの名前付け

ファイルの名前付けは、複数の単語で構成される場合、前のルールを参照します。例: error-report.html

複数の場合。構造には、スクリプト、スタイル、イメージ、データモデルなどの複数形の命名法を使用します

ファイル名は、小文字の英字 a ～ z、ソート番号 0 ～ 9、または区切り文字 - などの特殊記号のみで構成できます。 $ は禁止されています。

意味をよりよく表現するために、ファイル名には英語の名詞、または英語の略語が使用されています。

このモジュールがブラウザによってスパム広告として除外されるのを防ぐため、ad、adv、adver、advertising などの広告を含む英単語の名前を付けることは許可されません。これは、どのようなファイル命名にも当てはまります。

index.shtml ガイドページとホームページ

main.shtml ホームページ

download.shtml ダウンロードページ

act.html イベントリストページ

video.html ビデオ

cdkey.html CDKEY ページ

構文
ネストされたノードはインデントする必要があります (スペース 4 つ)。
自動終了タグの末尾にはスラッシュを使用しないでください。HTML5 仕様では、スラッシュはオプションであると規定されています。
```
![](images/logo.png)
```
ログイン後にコピー
HTML5 doctype
doctype は大文字と小文字を区別しませんが、慣例により大文字で表記されます
```
<!DOCTYPE html>
```
ログイン後にコピー
```
<html lang="en"></html>
```
ログイン後にコピー
文字エンコーディング

<meta charset="UTF-8">

ログイン後にコピー

IE 互換モード

IE は、現在のページの描画に使用する IE バージョンを決定するための特定のタグの使用をサポートしています。強い特別なニーズがない限り、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 を導入する場合、通常、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

プレースホルダー、title、alt

aria-*、role

ブール属性
一个元素中 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;
}
```
ログイン後にコピー
声明顺序
相关的属性声明应该以下面的顺序分组处理：
1. Positioning
2. Box model 盒模型
3. Typographic 排版
4. 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较慢，增加额外的页面请求，并可能导致其他不可预见的问题。
```
<link rel="stylesheet" href="core.css?1.1.11"><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
    }
})();
```
ログイン後にコピー