规范细则
-
基本原则
- 保证开发的有效性和合理性，并可最大程度的提高程序代码的可读性和可重复利用性。
- 符合web标准, 语义化html, 结构表现行为分离, 兼容性优良。
-
编码
[强制] 文件统一使用utf-8编码
-
代码风格
[强制] 使用2 个空格来代替制表符（tab），可以在IDE中进行设置。
[强制] 严格使用eslint代码约束。
HTML规范
语义化标签
- [强制] 标签名必须使用小写字母。
- [强制] HTML标签的使用应遵循标签的语义。
// good:
<h1>标题</h1>
// bad:
<p>标题</p>
- [强制] 标签使用必须符合标签嵌套规则。
- [强制] 禁止使用被废弃的用于表现的标签，如 center, font 等；
- [推荐] 对于属性的定义，确保全部使用双引号，不要使用单引号。
- [建议] 在 CSS 可以实现相同需求的情况下不得使用表格进行布局。
- [建议] 标签的使用应尽量简洁，减少不必要的标签。
格式
- [强制] 将每个块元素、列表元素或表格元素都放在新行；
- [建议] inline元素视情况换行，以长度不超过编辑器一屏为宜；
- [强制] 每个子元素都需要相对其父级缩进
注释
- [推荐] 尽可能的为你的代码写上注释。解释为什么要这样写，它是新鲜的方案还是解决了什么问题。
待办事项
- [推荐] 用 TODO 标示待办事项和正在开发的条目
属性
- [强制] 标签名必须使用小写字母。
- [建议] 属性值必须使用双引号包围。
- [建议] 自定义属性建议以 xxx- 为前缀，推荐使用data-。
- [建议] 布尔类型的属性，建议不添加属性值。
多媒体
- [强制] 禁止 img 的 src 取值为空。延迟加载的图片也要增加默认的 src。
- 解释：src 取值为空，会导致部分浏览器重新加载一次当前页面。
- [建议] 避免为 img 添加不必要的 title 属性。
- [建议] 为重要图片添加 alt 属性。
- [建议] 添加 width 和 height 属性，以避免页面抖动。
- [建议] 有下载需求的图片采用 img 标签实现，无下载需求的图片采用 CSS 背景图实现。
- 解释：
- 1、产品 logo、用户头像、用户产生的图片等有潜在下载需求的图片，以 img形式实现，能方便用户下载。
- 2、无下载需求的图片，比如：icon、背景、代码使用的图片等，尽可能采用 CSS 背景图实现。
表单
- [强制] 有文本标题的控件必须使用label标签将其与其标题相关联。
- [强制] 使用 button 元素时必须指明 type 属性值。
- 解释：button 元素的默认 type 为 submit，如果被置于 form 元素中，点击后将导致表单提交。为显示区分其作用方便理解，必须给出 type 属性。
- [建议] 尽量不要使用按钮类元素的 name 属性。
- 解释：由于浏览器兼容性问题，使用按钮的 name 属性会带来许多难以发现的问题。
JavaScript规范
文件
- [建议] JavaScript 文件使用无BOM 的 UTF-8 编码。
- [建议] 在文件结尾处，保留一个空行。
命名
- [强制] 变量、函数、函数参数、类的方法、命名空间及属性使用Camel命名法。 示例
：var taskModel = {};
- [强制] 常量 使用 全部字母大写，单词间下划线分隔 的命名方式。 示例
：var HTML_ENTER = {};
- [强制] 类 使用 Pascal命名法
- 示例：
function TextNode(options){};
- [强制] 类名 使用 名词。 示例：
function Engine(options) {}
- [建议] 函数名 使用 动宾短语。 示例：
function getStyle(element) {}
- [建议] boolean 类型的变量使用 is 、can、 has 开头。 示例：
var isReady = false;
- [建议] Promise对象 用 动宾短语的进行时 表达。：
var loadingData = ajax.get('url');
注释
- [强制] 必须独占一行。// 后跟一个空格，缩进与下一行被注释说明的代码一致。
- [建议] 自文档化的文档说明 what，而不是 how。
- [强制] 必须使用 @event 标识事件，事件参数的标识与方法描述的参数标识相同。
- [建议] 对于事件对象的注释，使用 @param 标识，生成文档时可读性更好。示例：
/**
* 值变更时触发
*
* @event Select#change
* @param {Object} e e描述
* @param {string} e.before before描述
* @param {string} e.after after描述
*/
语言特性
- [强制] 变量、函数在使用前必须先定义。
- [强制] 每个 var 只能声明一个变量。
- 一个 var声明多个变量，容易导致较长的行长度，并且在修改时容易造成逗号和分号的混淆。
- [强制] 变量必须即用即声明，不得在函数或其它形式的代码块起始位置统一声明所有变量。
- 解释：变量声明与使用的距离越远，出现的跨度越大，代码的阅读与维护成本越高。虽然JavaScript的变量是函数作用域，还是应该根据编程中的意图，缩小变量出现的距离空间。
- [强制] 在 Equality Expression 中使用类型严格的 ===。仅当判断 null 或 undefined 时，允许使用 == null。
- 使用 === 可以避免等于判断中隐式的类型转换。
- [建议] 尽可能使用简洁的表达式。 示例：
// good：
if (collection.length) {
// ......
}
// bad：
if (collection.length > 0) {
// ......
}
[建议] 原则上不建议使用全局变量，对于已有的全局变量或第三方框架引入的全局变量，需要根据检查工具的语法标识。 [建议] 按执行频率排列分支(分支语句)的顺序。 解释：按执行频率排列分支的顺序好处是：
- 阅读的人容易找到最常见的情况，增加可读性。
- 提高执行效率。
- [建议] 对于相同变量或表达式的多值条件，用 switch 代替 if。
- [强制] 如果函数或全局中的else块后没有任何语句，可以删除 else。
// good
function getName() {
if (name) {
return name;
}
return 'unnamed';
}
// bad
function getName() {
if (name) {
return name;
} else {
return 'unnamed';
}
}
结构
- [强制] [强制] switch 下的 case 和 default 必须增加一个缩进层级。
空格
- [强制] 二元运算符两侧必须有一个空格，一元运算符与操作对象之间不允许有空格。
- [强制] 用作代码块起始的左花括号 { 前必须有一个空格。
- [强制] if / else / for / while / function / switch / do / try / catch / finally关键字后，必须有一个空格。
- [强制] 在对象创建时，属性中的 : 之后必须有空格，: 之前不允许有空格。
- [强制] 函数声明、具名函数表达式、函数调用中，函数名和 ( 之间不允许有空格。
- [强制] , 和 ; 前不允许有空格。如果不位于行尾，, 和 ; 后必须跟一个空格。
换行
- [强制] 每个独立语句结束后必须换行。
- [强制] 每行不得超过 120 个字符。
- 解释：超长的不可分割的代码允许例外，比如复杂的正则表达式。长字符串不在例外之列。
- [强制] 在函数声明、函数表达式、函数调用、对象创建、数组创建、for 语句等场景中，不允许在 , 或 ; 前换行。 示例：
// good:
var obj = {
a: 1,
b: 2,
c: 3
}
// bad:
var obj = {
a: 1
, b: 2,
, c: 3
}
- [建议] 不同行为或逻辑的语句集，使用空行隔开，更易阅读。
- [强制] 函数定义结束不允许添加分号。
- [强制] IIFE 必须在函数表达式外添加括号，非 IIFE 不得在函数表达式外添加括号。
- 解释：IIFE = Immediately-Invoked Function Expression. 示例：
// good：
var task = (function () {
// Code
return result;
})();
// bad:
var task = function () {
// Code
return result;
}();
CSS规范
文件引用
- [强制] 一律使用link的方式调用外部样式
- [建议] 不允许使用 style 属性写行内样式。
属性书写顺序
- [建议]遵循先布局后内容的顺序。
- 影响文档流的属性（比如：display, position,float, clear, visibility, table-layout等）
- 自身盒模型的属性（比如：width, height, margin, padding, border等）
- 排版相关属性（比如：font, line-height, text-align, text-indent, vertical-align等等）
- 装饰性属性（比如：color, background, opacity, cursor等）
注释规范
- [强制]保持注释内容与星号之间有一个空格的距离
避免低效率选择器
- [建议]避免类型选择器
// bad
div#doc { sRules; }
li.first { sRules; }
// good
#doc { sRules; }
.first { sRules; }
- [建议]避免多重id选择器
命名
- [强制] 命名必须由单词、中划线或数字组成。
- 解释：我们使用中划线 “-” 作为连接字符，而不是下划线 "_"。我们知道2种方式都有不少支持者，但 "-" 能让你少按一次shift键，并且更符合CSS原生语法，所以我们只选一种目前业内普遍使用的方式
- [强制] ID和class的命名应反映该元素的功能或使用通用名称，而不要用抽象的晦涩的命名。
- [强制] 不允许使用拼音（约定俗成的除外，如：youku, baidu），尤其是缩写的拼音、拼音与英文的混合。
- [建议] 不依据表现形式来命名；
- [建议] 可根据内容来命名、可根据功能来命名
缩写规范
- 保证缩写后还能较为清晰保持原单词所能表述的意思；
- 使用业界熟知的或者约定俗成的。
书写格式
- [强制]选择器与大括号之间保留一个空格；
- [强制]分号之后保留一个空格；
- [强制]逗号之后保留一个空格；
- [强制]所有规则需换行；
- [强制]多组选择器之间需换行；
- [强制] 属性定义后必须以分号结尾。
- [建议] 使用 4 个空格做为一个缩进层级。
- [建议] 选择器的嵌套层级应不大于3级，位置靠后的限定条件应尽可能精确。
- [建议] 使用 border / margin / padding 等缩写时，应注意隐含值对实际数值的影响，确实需要设置多个方向的值时才使用缩写。
!important
- [建议] 尽量不使用 !important 声明。
- [建议] 当需要强制指定样式且不允许任何场景覆盖时，通过标签内联和 !important 定义样式。
- 解释： 必须注意的是，仅在设计上 确实不允许任何其它场景覆盖样式 时，才使用内联的 !important 样式。通常在第三方环境的应用中使用这种方案。下面的 z-index 章节是其中一个特殊场景的典型样例。
单位
- [强制] 如果属性值为0，则不需要为0加单位
- [建议] 如果是0开始的小数，前面的0可以省略不写
颜色
- [建议]将所有的颜色值小写；
- [建议]可以缩写的缩写至3位。
结语
坚持一致性的原则。 每个团队的代码风格如果统一了，首先可以培养良好的协同和编码习 惯，其次可以减少所谓的思考，再次可以提升代码质量和可维护性。 统一的代码风格，团队内部阅读或编辑代码，将会变得非常轻松，因为 所有组员都处在一致思维环境中。 最后如有错误或更优方案欢迎提出讨论，协商一致修改。
373
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
