优达学城（Udacity）前端样式指南

CSS 样式指南

点此查看文档英文版（pdf，GitHub.io）

简介

该指南是你在项目进行过程中所需遵守的官方指南。优达学城的评估人员会根据该指南为你的项目打分。在前端网页开发的世界中，有很"最佳"样式供你选择。因此，为了减少学生在项目过程中因选择何种样式所产生的困惑，我们强烈建议所有学生在其项目中遵循这个样式指南。

一般格式规则

字母大小写

仅使用小写。

所有代码均使用小写，该规则适用于 CSS 选择符、属性和属性值（字符串除外）。

不推荐：

color: #E5E5E5;

推荐：

color: #e5e5e5;

末尾空格

删除行尾空格。

行尾空格属于多余的符号，会使 diff 更加难以阅读。

不推荐：

border: 0;__

推荐：

border: 0;

如果使用 Sublime Text，你可在用户设置（User Settings）JSON 文件（可在文本编辑器的菜单中找到）中添加以下代码，每当你以此方法储存文件时，去除行尾空格操作便会自动完成：

"trim_trailing_white_space_on_save": true

缩进

整个文件中的缩进应保持前后一致，使用 Tab、2个空格或4个空格都可以，但需保持前后一致。

一般元规则

编码

使用 UTF-8（无 BOM）。

确保你的编辑器将没有字节顺序标记的 UTF-8 用作字符编码。不要将样式表的编码设置为假定的 UTF-8。

注释

在可行和必要时，对代码添加注释。

用注释解释代码的覆盖范围、目的和作用以及使用和选择各解决方案的原因。

任务项

用 TODO: 标注待办事项和任务项：

仅用关键词 TODO 标注待办事项，不要使用 @@ 等其他格式的字样。在任务项前加冒号，如：TODO: action item。

推荐：

/* TODO: 添加一个按钮元素 */

CSS 样式规则

CSS 有效性

使用有效的 CSS。

使用有效的 CSS 是可测量的基准质量，可确保 CSS 的合理使用并有助于识别可删除的无效 CSS 代码。

ID 和类名称

使用有意义或具有普遍性的 ID 和类名称。

不可使用意义含糊的 ID 和类名称，使用能够反映相应元素意义的名称或具有普遍性的通用名。

最好使用能够反映相应元素意义的具体名称，因为这些名称最易于理解且不易变更。

具有普遍性的通用名被用于与类似元素意义相仿的元素，主要起辅助作用。

不推荐：

 
xxxxxxxxxx
.p-998 { 
    … 
} 
​
.btn-green { 
    … 
}
​

推荐：

 
.gallery { 
    …
} 
​
.btn-default { 
    … 
}
​

类型选择符

避免用类型选择器限定 ID 和类名称。

除非情况需要（例如，在辅助类型中），否则不要将元素名和 ID 或类名称同时使用。为提高性能，避免使用不必要的祖先选择符。

在 CSS 文件中使用 ID 也是较糟糕的做法，类别始终比名称更具优势，如果你需要给予某元素一个特殊的名称，请使用类别。（ ID 的唯一优点是在存在数千个类似元素的页面上能保持较快的运行速度。）

不推荐：

 
xxxxxxxxxx
ul#example { 
    … 
} 
​
div.error { 
    … 
}
​

推荐：

 
xxxxxxxxxx
.example { 
    … 
} 
​
.error { 
    … 
}
​

简写属性

应使用简写。

CSS 可提供多种简写属性（例如，padding，而不是 padding-top、padding-bottom 等），应尽可能使用这些简写，但字体属性和在 Bootstrap 等框架中会覆盖其他同名属性的属性除外。

使用简写属性有助于提高代码的效率和易懂性。推荐在设置仅与字体 font 相关的属性时使用字体简写属性，但无需在进行小幅改动时使用。在使用字体简写属性时，请注意，如果未注明字体的大小和系列，浏览器会忽略整个字体声明。

不推荐：

 
x
border-top-style: none;
font-family: palatino, georgia, serif;
font-size: 100%; 
line-height: 1.6; 
padding-bottom: 2em; 
padding-left: 1em; 
padding-right: 1em; 
padding-top: 0;

推荐：

 
xxxxxxxxxx
border-top: 0; 
font: 100%/1.6 palatino, georgia, serif; 
padding: 0 1em 2em;
​

0和单位

去掉 0 值后面的单位。

不推荐：

 
xxxxxxxxxx
margin: 0em; 
padding: 0px;
​

推荐：

 
xxxxxxxxxx
margin: 0; 
padding: 0;
​

前导零

为方便阅读，十进制值中含有前导零。

不推荐：

font-size: .8em;

推荐：

font-size: 0.8em;

十六进制表示法

在可行时，使用三个十六进制表示法的字符。

不推荐：

color: #eebbcc;

推荐：

color: #ebc;

ID 和类名称分隔符

用连字符分隔 ID 和类名称中的字词（-）。

用连字符连接选择符中的词语和缩略词，以方便理解和扫描。

唯一的例外：在编写 BEM 样式 CSS 选择符时也可以使用下划线（_）。

不推荐：

 
xxxxxxxxxx
.demoimage { 
    … 
} 
​
.errorStatus {
     …
}
​

推荐：

 
xxxxxxxxxx
.demo-image { 
    … 
} 
​
.error-status { 
    … 
}
​

Hack

避免用户代理检测或 CSS Hack ——尝试另一种方法。

人们可能很想处理用户代理检测或特殊的 CSS 过滤器以及应变方案和非法入侵之间的样式差异。这两项措施均为实现和维护有效和可处理的代码库的最后方案。请考虑该样式是否对应用的性能至关重要，需要该样式的用户代理是否可以不采样该样式。

CSS 格式规则

代码块内容缩进

缩进所有代码块内容，即规则内的规则和声明，以反映层次结构、方便理解。

推荐：

 
@media screen, projection { 
    html { 
        background: #fff; 
        color: #444; 
    } 
}
​

声明标点

在所有声明后使用分号，以增加连贯性和延展性。

不推荐：

 
xxxxxxxxxx
.test { 
    display: block; 
    height: 100px 
}
​

推荐：

 
xxxxxxxxxx
.test { 
    display: block;
    height: 100px; 
}
​

属性名标点

所有属性名冒号后均需添加空格，但属性和冒号间不加空格，以增加连贯性。

不推荐：

 
xxxxxxxxxx
font-weight:bold;
padding : 0;
margin :0;
​

推荐：

 
xxxxxxxxxx
font-weight: bold;
padding: 0; 
margin: 0;
​

声明区标点

最后一个选择符和声明区起始处的左大括号之间需加空格。

不推荐：

 
xxxxxxxxxx
.video-block{ 
    margin: 0; 
} 
​
.audio-block{ 
    margin: 0;
}
​

推荐：

 
xxxxxxxxxx
.video-block { 
    margin: 0; 
} 
​
.audio-block { 
    margin: 0; 
}
​

选择符和声明分隔

所有选择符和声明均需另起一行。

不推荐：

 
xxxxxxxxxx
h1, h2, h3 { 
    font-weight: normal; 
    line-height: 1.2; 
}
​

推荐：

 
xxxxxxxxxx
h1, 
h2, 
h3 { 
    font-weight: normal; 
    line-height: 1.2; 
}
​

规则分隔

所有规则间均需加一个空行（两个换行符）。

推荐：

 
xxxxxxxxxx
html { 
    background: #fff; 
} 
​
body { 
    margin: auto; 
    width: 50%; 
}
​

CSS 引号

属性选择符和属性值均需使用双引号，链接值（ url()）中不可使用双引号。

不推荐：

 
xxxxxxxxxx
@import url("css/links.css"); 
html { 
    font-family: 'Open Sans', arial, sans-serif; 
}
​

推荐：

 
xxxxxxxxxx
@import url(css/links.css); 
html { 
    font-family: "Open Sans", arial, sans-serif; 
}
​

CSS 元规则

区块注释

在可行时，用注释将样式表区块组合在一起，用新行分隔各区块。

推荐：

 
xxxxxxxxxx
/* Header */
.header {
…
}
​
.header-nav {
…
}
​
/* Content */
.gallery {
…
}
​
.gallery-img {
…
}
​
/* Footer */
.footer {
…
}
​
.footer-nav {
…
}

JavaScript 样式指南

点此查看文档英文版（pdf，GitHub.io）

简介

该指南是你在项目进行过程中所需遵守的官方指南。优达学城的评估人员会根据该指南为你的项目打分。在前端网页开发的世界中，有很"最佳"样式供你选择。因此，为了减少学生在项目过程中因选择何种样式所产生的困惑，我们强烈建议所有学生在其项目中遵循这个样式指南。

一般格式规则

末尾空白

删除行尾空格。

行尾空格属于多余的符号，会使 diff 更加难以阅读。

不推荐：

var name = "John Smith";__

推荐：

var name = "John Smith";

如果使用 Sublime Text，你可在用户设置（User Settings）JSON 文件（可在文本编辑器的菜单中找到）中添加以下代码，每当你以此方法储存文件时，去除行尾空格操作便会自动完成：

"trim_trailing_white_space_on_save": true

缩进

整个文件中的缩进应保持前后一致，使用 Tab、2个空格或4个空格都可以，但需保持前后一致。

一般元规则

编码

使用 UTF-8（无 BOM）。

确保你的编辑器将没有字节顺序标记的 UTF-8 用作字符编码。

注释

用注释解释代码的覆盖范围、目的和作用以及使用和选择各解决方案的原因。

你可以选择使用 JSDoc，即编写代码注释的文件生成器和标准，对你的 JavaScript 功能进行记录，其优点包括为你的注释提供技术参照和能够针对文件生成网页的命令行 jsdoc 工具。 JSDoc 会为你提供记录代码的多种注释，但我们只推荐你使用以下种类：

• @constructor：用于记录类别，即用新关键词调用的函数。
• @description：用于描述你的函数，该标签还可以使你在需要时添加 HTML 标记。
• @param：用于描述函数参数的名称、类别和说明。
• @returns：记录函数返回值的类型和说明。

该实例说明了如何记录类构造器（注意注释区开头使用的 /**，这个非常重要）：

 
xxxxxxxxxx
/**
* @description 简要描述这本书
* @constructor
* @param {string} title - 书的标题
* @param {string} author - 书的作者
*/
​
function Book(title, author) {
    ...
}

以下函数含有能返回值的参数，注意，这里的参数作用一目了然，因此并未对其进行说明。

 
xxxxxxxxxx
/**
* @description 添加两个数字
* @param {number} a
* @param {number} b
* @returns {number} 数字 a 与 b 的和
*/
​
function sum(a, b) {
    return a + b;
}

你也可以使用更多你想要编写的注释。

任务项

用 TODO: 标注待办事项和任务项：

仅用关键词 TODO 标注待办事项，不要使用 @@ 等其他格式的字样。在任务项前加冒号，如： TODO: 要做的事

推荐：

// TODO: 加些其他的需求

JavaScript 语言规则

变量

在 JavaScript 里一共有三种定义变量的方式：

• const
• let
• var

当定义变量的时候，你应该使用上面列出的关键字来定义变量。优先考虑使用 const 定义你的变量，如果觉得以后需要对变量重新赋值的，则使用 let。现在已经不推荐使用 var 关键字来定义变量了

分号

始终使用分号。

依靠隐式插入会造成难以排除的细微问题。分号应放在函数表达式的末尾，而不是函数声明的末尾。

不推荐：

 
xxxxxxxxxx
var foo = function() {
    return true // 缺少分号
} // 缺少分号

 
xxxxxxxxxx
function foo() {
    return true;
}; // 额外的分号

推荐：

 
xxxxxxxxxx
var foo = function() {
    return true;
};

 
xxxxxxxxxx
function foo() {
    return true;
}

基本类型包装对象

基本类型无需使用包装对象，此外，包装对象还具有潜在危险，但可以使用类型转换。

不推荐：

 
xxxxxxxxxx
var x = new Boolean(0);
if (x) {
    alert('hi');    // 如果 x 是一个真实对象，则显示 hi
}

推荐：

 
xxxxxxxxxx
var x = Boolean(false);
if (x) {
    alert('hi');    // 如果 x 是一个否定的布尔值，则显示 hi
}

闭包

进行该操作时要小心谨慎。 创建闭包的能力可能是 JavaScript 中最有用但最常被忽略的能力。需要记住的是，闭包会储存对其封闭范围的指示器，因此，将 DOM 元素与闭包相连会生成循环引用，从而导致内存的泄露。

不推荐：

 
xxxxxxxxxx
function foo(element, a, b) {
    element.onclick = function() { /* 使用 a 和 b */ }
}

推荐：

 
xxxxxxxxxx
function foo(element, a, b) {
    element.onclick = bar(a, b);
}

 
xxxxxxxxxx
function bar(a, b) {
    return function() { /* 使用 a 和 b */ }
}

for 、for-in 和 forEach

数组

在迭代数组时，相比 for-in 循环， forEach 或 for 循环更具优势。

不推荐：

 
xxxxxxxxxx
myArray = ['a', 1, 'etc'];
for (var indexNum in myArray) {
    console.log(myArray[indexNum]);
}
var starWars = {
    "creatures": [
        {
            "name": "bantha",
            "face": "furry"
        },
        {
            "name": "loth-cat",
            "face": "toothy"
        }
    ]
};
for (var i in starWars.creatures) {
    console.log(starWars.creatures[i].name);
    console.log(starWars.creatures[i].face);
};

推荐：

 
xxxxxxxxxx
mySimpleArray = ['a', 1, 'etc'];
mySimpleArray.forEach(function(val) {
    console.log(val);
});
var starWars = {
    "creatures": [
        {
            "name": "bantha",
            "face": "furry"
        },
        {
            "name": "loth-cat",
            "face": "toothy"
        }
    ]
};
starWars.creatures.forEach(function(creature){
    console.log(creature.name);
    console.log(creature.face)
});
// 或者
myArray = ['a', 1, 'etc'];
for (var indexCount = 0; indexCount < myArray.length; indexCount++) {
    console.log(myArray[indexCount]);
};

对象

for-in 循环用于在对象中循环关键词。这样很容易出错，因为， for-in 不会从 0 循环，而是循环对象及其原型链中现存的所有关键词。 如果可以的话，对数据进行整理，以避免迭代对象。如果不可行，将 for-in 循环的内容包裹在条件语句中，以避免迭代原型链。

不推荐：

 
xxxxxxxxxx
myObj = {'firstName':'Ada','secondName':'Lovelace'};
for (var key in myObj) {
    console.log(myObj[key]);
}

推荐：

 
xxxxxxxxxx
myObj = {'firstName':'Ada','lastName':'Lovelace'};
for (var key in myObj) {
    if (myObj.hasOwnProperty(key)) {
        console.log(myObj[key]);
    }
}

多行字符串字面量

不要使用。 编译期间无法妥善删除各行开头的空格，斜杠后的空白会引发棘手的问题，虽然大部分脚本引擎支持该操作，但这并不属于规格中的一部分。

不推荐：

 
xxxxxxxxxx
var myPoetry = '一二三四五，\
    上山打老虎，\
    老虎没打到，\
    打到小松鼠，\
    让我数一数，\
    一二三四五';

推荐：

 
xxxxxxxxxx
var myPoetry = '黄河远上白云间，' +
    '一片孤城万仞山。' +
    '羌笛何须怨杨柳，' +
    '春风不度玉门关。';

数组和对象字面量

使用数组和对象字面量，而不是数组和对象构造函数。

不推荐：

 
xxxxxxxxxx
var myArray = new Array(x1, x2, x3);
var myObject = new Object();
myObject.a = 0;

推荐：

 
xxxxxxxxxx
var myArray = [x1, x2, x3];
var myObject = {
    a: 0
};

JavaScript 样式规则

命名

总体来说，函数名称为 functionNames ，变量名称为 variableNames ，类名称为 ClassNames ，方法名称为 methodNames ，常量值名称为 CONSTANT_VALUES ，文件名称为 filenames 。

代码格式

由于分号的隐式插入，大括号应与其内容放置在同一行。

推荐：

 
xxxxxxxxxx
if (something) {
    // 执行某项任务
} else {
    // 执行另外一项任务
}

只有在单行数组和对象初始器可以在写同一行时方可使用这两项。左括号前和右括号后都不应有空格。

推荐：

 
xxxxxxxxxx
var array = [1, 2, 3];
var object = {a: 1, b: 2, c: 3};

多行数组和对象初始器需进行单行缩进，与代码块一样，其括号与内容应位于同一行。

推荐：

 
xxxxxxxxxx
var array = [
    'Joe <joe@email.com>',
    'Sal <sal@email.com>',
    'Murr <murr@email.com>',
    'Q <q@email.com>'
];
​
var object = {
    id: 'foo',
    class: 'foo-important',
    name: 'notification'
};
​

插入语

仅在需要时使用。 仅在语法和语义需要时少量、概括性地使用。

字符串

为了保持连贯性，应使用单引号 ' 而不是双引号 "。这在创建含有 HTML 的字符串时尤其有帮助。

推荐：

var element = '<button class="btn">Click Me</button>';

此规则较为明显的一个例外是在 JSON 对象中： JSON 要求使用双引号。

技巧提示

真假布尔表达式 以下为假的布尔表达式：

• Null
• undefined
• '' the empty string
• 0 the number

注意区分，以下为真的表达式：

• '0' the string
• [] the empty array
• {} the empty object

三元条件运算符

不强制规定，但建议使用三元条件运算符编写简洁代码，避免使用以下代码：

不推荐：

 
xxxxxxxxxx
if (val) {
    return foo();
} else {
    return bar();
}
​

推荐：

return val ? foo() : bar();

&& 和 ||

这些二元布尔运算符为简化形式，会计算至最后一个已计算项。 || 被称为默认的运算符，这是因为不应以下列方式编写代码：

不推荐：

 
xxxxxxxxxx
function foo(name) {
    var theName;
    if (name) {
        theName = name;
    } else {
        theName = 'John';
    }
}

推荐：

 
xxxxxxxxxx
function foo(name) {
    var theName = name || 'John';
}

&& 也被用于缩减代码

不推荐：

 
xxxxxxxxxx
if (node) {
    if (node.kids) {
        console.log(node.kids);
    }
}

推荐：

 
xxxxxxxxxx
if (node && node.kids) {
    console.log(node.kids);
}

Git 提交信息样式指南

点此查看文档英文版（pdf，GitHub.io）

简介

该指南是你在项目进行过程中所需遵守的官方指南。优达学城的评估人员会根据该指南为你的项目打分。在前端网页开发的世界中，有很“最佳”样式供你选择。因此，为了减少学生在项目过程中因选择何种样式所产生的困惑，我们强烈建议所有学生在其项目中遵循这个样式指南。

提交信息

信息结构

提交信息由三个不同的部分构成，这些部分均由空行分隔：标题、可选的消息体和可选的注释。其布局大致如此：

 
xxxxxxxxxx
类型：主题
消息正文
注释

标题由消息类型和主题构成。

类型

类型位于在标题内，有以下几种可能：

• feature： 新功能
• fix：错误修复
• docs：文档修改
• style：格式、分号缺失等，代码无变动
• refactor：生产代码重构
• test：测试添加、测试重构等，生产代码无变动
• chore：构建任务更新、程序包管理器配置等，生产代码无变动。

标题

主题不得超过50个字符，首字母大写，末尾不加句号。 以祈使语气描述提交的任务，而不是其已完成的任务。例如，使用 change...，而不是 changed 或 changes 。

信息正文

并不是所有的提交信息都复杂到需要主体，因此这是可选内容，仅在提交信息需要一定的解释和语境时使用。消息体是用于解释提交任务的内容和原因，而不是方法。

在编写正文时，需要在标题和正文间加一个空行，且每行的内容应控制在72个字符内。

注释

注释是可选内容，用于引用问题跟踪的 ID 。

提交信息示例

 
xxxxxxxxxx
Feature: 总结变动的内容，保持在50个字符内
​
如有需要，使用更详细的说明性文字，将其大概控制在72个字符。在部分语境中，第一行被视为提交信息的主题，余下的文本被视为主体。分隔总结与主体的空行十分重要（除非你完全忽略主体）；否则`log`、`shortlog`和`rebase`等多个工具容易发生混淆。
解释该提交信息所解决的问题，说明你进行该变动的原因，而不是方法（代码本身可以解释方法）。
该变动是否存在副作用或其他直觉性后果？在这里进行解释。
​
后续段落前需加空行。
可以列出要点
- 通常情况下，要点会使用空格加上连字符或星号，中间用空行分隔，但该规定存在差别。
​
如果你使用问题追踪，将其引用放在末尾，例如：
解决了问题：#123
另见：#456, #789