Authored by xuqi

规范整合简化

1 # JavaScript代码规范 1 # JavaScript代码规范
2 2
3 -## 缩进  
4 -缩进由**4个空格**组成(由于tab在各编辑器和系统之间解析有差异,所以建议使用空格)  
5 -  
6 ## 行的长度 3 ## 行的长度
7 -每行长度不应该超过**120**个字符,如果一行多余120个字符,应该在一个运算符后换行,下一行增加**2**级缩进,即8个空格) 4 +每行长度不应该超过**80**个字符,如果一行多余80个字符,应该在一个运算符后换行,下一行增加**2**级缩进,即8个空格)
8 5
9 doSomething(argument1, argument2, argument3, argument4, 6 doSomething(argument1, argument2, argument3, argument4,
10 argument5); 7 argument5);
@@ -32,13 +29,20 @@ @@ -32,13 +29,20 @@
32 var str = 'I am a programer.I love JS and \ 29 var str = 'I am a programer.I love JS and \
33 Node'; 30 Node';
34 31
  32 +##空行
  33 +* 方法之间添加空行分隔
  34 +* 单行或多行注释前添加空行
  35 +* 逻辑块之间添加空行增加可读性
  36 +
35 ## null使用场景 37 ## null使用场景
36 * 用来初始化一个变量,该变量可能被赋值为一个对象 38 * 用来初始化一个变量,该变量可能被赋值为一个对象
37 * 用来和一个已经初始化的变量比较 39 * 用来和一个已经初始化的变量比较
38 * 当函数的参数期望为对象时,被用作参数传入 40 * 当函数的参数期望为对象时,被用作参数传入
39 * 当函数的返回值期望是对象时,被用作返回值传出 41 * 当函数的返回值期望是对象时,被用作返回值传出
  42 +
40 ## undefined 43 ## undefined
41 禁止使用`name === undefined`判断一个变量是否定义。应该使用`typeof(name) === 'undefined'`; 44 禁止使用`name === undefined`判断一个变量是否定义。应该使用`typeof(name) === 'undefined'`;
  45 +
42 ## 对象直接量 46 ## 对象直接量
43 * 起始左括号应该与表达式保持一行 47 * 起始左括号应该与表达式保持一行
44 * 每个属性的键名前保持一个缩进,第一个属性应该在左括号后另一起行 48 * 每个属性的键名前保持一个缩进,第一个属性应该在左括号后另一起行
@@ -80,19 +84,16 @@ @@ -80,19 +84,16 @@
80 sex, 84 sex,
81 ... 85 ...
82 86
  87 +另外,变量名需要给出注释,否则别人很难读懂接下来代码的意思。
  88 +
83 #### 变量术语约定 89 #### 变量术语约定
84 -* `get/set` 不要和一个字段相连,除非它被定义为私有变量  
85 -* 前缀为`is`的变量名 应该 为布尔值,同理可以为`has`,`can` 或者`should`  
86 -* `compute`作为变量名应为已经计算完成的变量  
87 -* `find`作为变量名应为已经查找完成的变量  
88 -* `initialize`或者`init`作为变量名应为已经实例化(初始化)完成的类或者其他类型的变量  
89 -* UI控制变量应在名称后加控制类型,例如:leftComboBox, topScrollPane  
90 -* 如果变量表示多个实例,必须用复数单词,如:cats  
91 -* 带有 `num` 或者 `count` 开头的变量名约定为数字  
92 -* 重复变量建议使用 `i`, `j`, `k` (依次类推)等名称的变量  
93 -* 能缩写的名称尽量使用缩写。如:prod表示产品  
94 -* 避免产生歧义的布尔变量名称,例如:isNotError, isNotFound为非法  
95 -* 错误类建议在变量名称后加上 `Exception` 或者 `Error` 90 +变量可以按照一定规则命名也表示某些特定功能,比如:
  91 +
  92 +* is前缀可以表示boolean值
  93 +* num或者count表示计数
  94 +* 错误加上Exception或者Error后缀
  95 +* ...
  96 +
96 ### 函数 97 ### 函数
97 * 函数在使用前应该先定义 98 * 函数在使用前应该先定义
98 * 函数名和开始圆括号之间无空格(包括匿名函数的function关键字与圆括号之间) 99 * 函数名和开始圆括号之间无空格(包括匿名函数的function关键字与圆括号之间)
@@ -110,22 +111,53 @@ @@ -110,22 +111,53 @@
110 doSomething(); 111 doSomething();
111 }; 112 };
112 113
  114 +另外,IIFE的标准格式也在这里指出:
  115 +
  116 + (function(args) {
  117 + //
  118 + }(args)); //(args)位于外层括号内
  119 +
  120 +其他声明函数需要注意的方面:
  121 +
  122 +* 循环中切勿加入函数,很容易因为闭包的原因造成错误。
  123 +
  124 + //BAD
  125 + for(i = 0; i < 3; i++) {
  126 + setTimeout(function() {
  127 + console.log(i);
  128 + }, 0);
  129 + }
  130 +
  131 +* “代码块”中切勿加入函数声明,混淆作用域
  132 +
  133 + //BAD
  134 + if (conditions) {
  135 + function() {
  136 + //doSomethings
  137 + }
  138 + }
  139 +
113 ## 命名 140 ## 命名
114 ### 变量: 141 ### 变量:
115 * 采用小驼峰命名格式 142 * 采用小驼峰命名格式
116 * 变量命名为名词(区别函数) 143 * 变量命名为名词(区别函数)
117 * 变量中不使用_ 144 * 变量中不使用_
  145 +
118 ### 常量: 146 ### 常量:
119 * 所有字符大写,不同单词之间适用单个下划线隔开 147 * 所有字符大写,不同单词之间适用单个下划线隔开
  148 +
120 ### 函数: 149 ### 函数:
121 * 采用小驼峰命名格式 150 * 采用小驼峰命名格式
122 * 函数命名为动词(区别变量) 151 * 函数命名为动词(区别变量)
123 * 函数名中是使用_ 152 * 函数名中是使用_
  153 +
124 ### 构造函数: 154 ### 构造函数:
125 * 采用大驼峰命名格式 155 * 采用大驼峰命名格式
126 * 命名应该是名词 156 * 命名应该是名词
  157 +
127 ### 私有成员: 158 ### 私有成员:
128 * 一个对象中不希望外部访问的以下划线开头(约定) 159 * 一个对象中不希望外部访问的以下划线开头(约定)
  160 +
129 ## 表达式 161 ## 表达式
130 ### 赋值 162 ### 赋值
131 当给变量赋值时,如果右侧是含有比较语句等形式的表达式时,用圆括号包裹 163 当给变量赋值时,如果右侧是含有比较语句等形式的表达式时,用圆括号包裹
@@ -191,7 +223,8 @@ @@ -191,7 +223,8 @@
191 223
192 #### switch语句 224 #### switch语句
193 * 每一个case保持一个缩进,除第一个之外包括default在内的每一个case都应该在之前保留一个空行 225 * 每一个case保持一个缩进,除第一个之外包括default在内的每一个case都应该在之前保留一个空行
194 -* 每一组语句都应该以break,return等结尾,或者用一行注释表示跳过 226 +* 每一组语句都应该以break,return等结尾,或者用一行注释表示跳过(falling through)
  227 +* 无default的情况也要注释特别说明
195 228
196 switch (val) { 229 switch (val) {
197 case 1: 230 case 1:
@@ -232,6 +265,15 @@ @@ -232,6 +265,15 @@
232 * date 265 * date
233 */ 266 */
234 267
  268 +函数的说明也采取类似格式:
  269 +
  270 + /**
  271 + * 函数功能描述
  272 + * @param ...
  273 + * @returns ...
  274 + */
  275 +[标签说明](http://usejsdoc.org/)
  276 +
235 ### JQuery插件规范 277 ### JQuery插件规范
236 * 文件命名为jquery.plugin-name.js 278 * 文件命名为jquery.plugin-name.js
237 * 所有新方法附加到jquery.fn对象,所有新功能附加到jquery对象 279 * 所有新方法附加到jquery.fn对象,所有新功能附加到jquery对象
@@ -239,105 +281,4 @@ @@ -239,105 +281,4 @@
239 * 插件的开头带一个`;`,防止代码合并出现问题 281 * 插件的开头带一个`;`,防止代码合并出现问题
240 * 除特殊注明外,所有方法必须返回jquery对象以便于链式调用 282 * 除特殊注明外,所有方法必须返回jquery对象以便于链式调用
241 * 使用this.each迭代匹配的元素 283 * 使用this.each迭代匹配的元素
242 -* 在插件代码中使用`JQuery`而不是`$`,减少命名冲突对我们的影响  
243 -  
244 -### 全局命名空间污染与 IIFE  
245 -总是将代码包裹成一个IIFE(Immediately-Invoked Function Expression),用以创建独立隔绝的定义域,防止全局命名空间被污染。  
246 -  
247 - //GOOD  
248 - (function(log, w, undefined){  
249 - 'use strict';  
250 -  
251 - var x = 10,  
252 - y = 100;  
253 -  
254 - // Will output 'true true'  
255 - log((w.x === undefined) + ' ' + (w.y === undefined));  
256 -  
257 - }(window.console.log, window));  
258 -  
259 - //BAD  
260 - var x = 10,  
261 - y = 100;  
262 - // Declaring variables in the global scope is resulting in global scope pollution. All variables declared like this  
263 - // will be stored in the window object. This is very unclean and needs to be avoided.  
264 - console.log(window.x + ' ' + window.y);  
265 -  
266 -立即执行的函数表达式的执行括号应该写在外包括号内。虽然写在内还是写在外都是有效的,但写在内使得整个表达式看起来更像一个整体,因此推荐这么做。like: `(function(){}());`  
267 -so,用下列写法来格式化你的 IIFE 代码:  
268 -  
269 - (function(){  
270 - 'use strict';  
271 -  
272 - // Code goes here  
273 -  
274 - }());  
275 -  
276 -如果你想引用全局变量或者是外层 IIFE 的变量,可以通过下列方式传参:  
277 -  
278 - (function($, w, d){  
279 - 'use strict';  
280 -  
281 - $(function() {  
282 - w.alert(d.querySelectorAll('div').length);  
283 - });  
284 - }(jQuery, window, document));  
285 -  
286 -### 严格模式  
287 -use strict;  
288 -  
289 -### 语句块内的函数声明  
290 -切勿在语句块内声明函数,在 ECMAScript 5 的严格模式下,这是不合法的。函数声明应该在定义域的顶层。但在语句块内可将函数申明转化为函数表达式赋值给变量。  
291 -  
292 - //BAD  
293 - if (x) {  
294 - function foo() {}  
295 - }  
296 - //GOOD  
297 - var foo;  
298 - if (x) {  
299 - foo = function() {};  
300 - }  
301 -  
302 -### 标准特性  
303 -总是优先考虑使用标准特性。从性能、扩展性、兼容性方面考虑,总是首选标准的特性(e.g.:首选 string.charAt(3) 而不是 string[3])。  
304 -  
305 -### 切勿在循环中创建函数  
306 -在简单的循环语句中加入函数是非常容易形成闭包而带来隐患的  
307 -  
308 - //GOOD  
309 - (function(log, w){  
310 - 'use strict';  
311 - //  
312 - var numbers = [1, 2, 3],  
313 - i;  
314 -  
315 - numbers.forEach(function(number, index) {  
316 - w.setTimeout(function() {  
317 - w.alert('Index ' + index + ' with number ' + number);  
318 - }, 0);  
319 - });  
320 -  
321 - }(window.console.log, window));  
322 -  
323 - //BAD  
324 - (function(log, w){  
325 - 'use strict';  
326 - //  
327 - var numbers = [1, 2, 3],  
328 - i;  
329 -  
330 - for(i = 0; i < numbers.length; i++) {  
331 - w.setTimeout(function() {  
332 - w.alert('Index ' + i + ' with number ' + numbers[i]);  
333 - }, 0);  
334 - }  
335 -  
336 - }(window.console.log, window));  
337 -  
338 -  
339 -### this  
340 -限制this使用场景  
341 -  
342 -* 在构造函数中  
343 -* 在对象的方法中(包括由此创建出的闭包内)  
  284 +* 在插件代码中使用`JQuery`而不是`$`,减少命名冲突对我们的影响
1 # css / sass代码规范 1 # css / sass代码规范
2 2
3 -## id和class命名  
4 -id和class总是使用可以反应元素目的和用途的名称,或其他通用名称。而不使用表象或者晦涩难懂的名称。  
5 -  
6 - //GOOD  
7 - .heavy {  
8 - font-weight: 800;  
9 - }  
10 -  
11 - .important {  
12 - color: red;  
13 - }  
14 -  
15 - //BAD  
16 - .fw-800 {  
17 - font-weight: 800;  
18 - }  
19 -  
20 - .red {  
21 - color: red;  
22 - }  
23 -  
24 -## 合理的避免使用id  
25 -一般情况下id不应该被应用于样式,id选择器权重很高,样式很难被覆盖  
26 -  
27 - //GOOD  
28 - .content .title {  
29 - font-size: 2em;  
30 - }  
31 -  
32 - //BAD  
33 - #content .title {  
34 - font-size: 2em; 3 +## 选择器
  4 +* 使用class进行样式匹配,而不是id和标签
  5 +* 避免使用属性选择器,会影响浏览器性能
  6 +* 控制选择器长度,每个组合应该控制在3个以内
  7 +* 尽可能精确的元素定位
  8 +
  9 +## 规则细节
  10 +
  11 + .ele-header, /*规则1:每个选择器声明总是使用新的一行*/
  12 + .ele-body,
  13 + .ele-footer { /*规则2:'{' 前需要添加1个空格*/
  14 + line-height: 1.2; /*规则3;样式声明以;结束,每个样式声明独占一行*/
  15 + font-weight: normal; /*规则4:属性声明的:后添加1个空格*/
  16 + margin: 0; /*规则5:属性值为0时不添加单位*/
  17 + background-color: #f3d; /*规则6:十六进制小写和缩写*/
  18 + }
  19 + /*规则7:没组选择器声明之间适用一空行间隔*/
  20 + .ele2 {
  21 + font-family: "open sans", arial, sans-serif; /*规则8:使用" ",而不是' '*/
  22 + padding: 0 1em 2em; /*规则9:适当缩写但不滥用*/
  23 + border-top: 1px;
  24 + background-color: rgba(0,0,0,.5); /*规则10:颜色值rgba等中不需要增加空格,并且去除浮点数前面不必要的0*/
35 } 25 }
36 26
37 -## CSS选择器中避免标签名  
38 -当构建选择器时应该使用清晰、准确和有语义的class名,而不使用标签选择器。从分离的角度考虑,在表现层中不应该分配html标记/语义。  
39 -  
40 - //GOOD  
41 - .content > .content-header > .title {  
42 - font-size: 2em;  
43 - }  
44 -  
45 - //BAD  
46 - div.content > header.content-header > h2.title {  
47 - font-size: 2em;  
48 - }  
49 -  
50 -## 尽可能的精确  
51 -很多前端开发人员写选择器链的时候不使用直接子选择器(区别于后代选择器)。有时,这可能会导致疼痛的设计问题并且有时候可能会很耗性能。然而,在任何情况下,这是一个非常不好的做法。如果你不写很通用的,需要匹配到DOM末端的选择器, 你应该总是考虑直接子选择器。  
52 -  
53 -## 缩写属性  
54 -CSS提供了各种缩写属性(如 font 字体)应该尽可能使用,即使在只设置一个值的情况下。使用缩写属性对于代码效率和可读性是有很有用的。  
55 -  
56 - //GOOD  
57 - border-top: 0;  
58 - font: 100%/1.6 palatino, georgia, serif;  
59 - padding: 0 1em 2em;  
60 -  
61 - //BAD  
62 - border-top-style: none;  
63 - font-family: palatino, georgia, serif;  
64 - font-size: 100%;  
65 - line-height: 1.6;  
66 - padding-bottom: 2em;  
67 - padding-left: 1em;  
68 - padding-right: 1em;  
69 - padding-top: 0;  
70 -  
71 -## 0和单位  
72 -省略“0”值后面的单位。不要在0值后面使用单位,除非有值。  
73 -  
74 - //GOOD  
75 - padding-bottom: 0;  
76 - margin: 0;  
77 -  
78 - //BAD  
79 - padding-bottom: 0px;  
80 - margin: 0em;  
81 -  
82 -## 十六进制表示法  
83 -始终使用**小写**以及**简写**的十六进制数字  
84 -  
85 - //GOOD  
86 - color: #f3a;  
87 -  
88 - //BAD  
89 - color: #FF33AA;  
90 -  
91 -## id和class名的分隔符  
92 -使用连字符(`-`)分隔id和class名中的单词。  
93 -  
94 - //GOOD  
95 - .video-id {}  
96 - .ads-sample {}  
97 -  
98 - //BAD  
99 - .demoimage {}  
100 - .error_status {}  
101 -  
102 ## 声明顺序 27 ## 声明顺序
103 这是一个选择器内书写CSS属性顺序的大致轮廓,作为最佳实践,我们应该遵循以下顺序: 28 这是一个选择器内书写CSS属性顺序的大致轮廓,作为最佳实践,我们应该遵循以下顺序:
104 29
105 -1. 结构性属性:  
106 - display,  
107 - position, left, top, right,  
108 - overflow, float, clear,  
109 - margin, padding  
110 - ...  
111 -2. 表现性属性:  
112 - background, border,  
113 - font, text  
114 - ...  
115 -  
116 - //GOOD  
117 - .box {  
118 - display: block;  
119 - position: absolute;  
120 - left: 30%;  
121 - right: 30%;  
122 - overflow: hidden;  
123 - margin: 1em;  
124 - padding: 1em;  
125 - background-color: #eee;  
126 - border: 3px solid #ddd;  
127 - font-family: 'Arial', sans-serif;  
128 - font-size: 1.5rem;  
129 - text-transform: uppercase;  
130 - } 30 +* Position属性 (position,top,right,z-index...)
  31 +* Box Model属性 (display,float,width...)
  32 +* Typographic属性 (font,line-height,color,text-align...)
  33 +* Visual属性 (background,border,border-radius...)
131 34
132 -## 声明结束  
133 -为了保证一致性和可扩展性,每个声明应该用分号结束,每个声明换行。 35 +因为Position属性可以是一个元素脱离正常的文本流并可以覆盖盒模型相关样式,所以Position排第一位。盒模型决定一个元素位置和大小紧跟其后。后面属性属于元素内部或不会对前两者产生影响的,排在后面。
134 36
135 - //GOOD  
136 - .test {  
137 - display: block;  
138 - height: 100px;  
139 - }  
140 -  
141 - //BAD  
142 - .test {  
143 - display: block; height: 100px  
144 - }  
145 -  
146 -## 属性名结束  
147 -属性名的冒号后使用一个空格。出于一致性的原因,属性和值(但属性和冒号之间没有空格)的之间始终使用一个空格。  
148 -  
149 - //GOOD  
150 - h3 {  
151 - font-weight: bold;  
152 - }  
153 -  
154 - //BAD  
155 - h3 {  
156 - font-weight:bold;  
157 - }  
158 -  
159 -## 选择器和声明分离  
160 -每个选择器和属性声明总是使用新的一行。  
161 -  
162 - //GOOD  
163 - h1,  
164 - h2,  
165 - h3 {  
166 - font-weight: normal;  
167 - line-height: 1.2;  
168 - }  
169 - //BAD  
170 - a:focus, a:active {  
171 - position: relative; top: 1px;  
172 - } 37 +完整属性顺序参考[Recsss](http://twitter.github.com/recess)
173 38
174 -## 规则分隔  
175 -规则之间始终有一个空行分隔。 39 +## 媒体查询
  40 +媒体查询的位置靠近他们相关的规则。
176 41
177 //GOOD 42 //GOOD
178 - html {  
179 - background: #fff;  
180 - }  
181 -  
182 - body {  
183 - margin: auto;  
184 - width: 50%; 43 + @media (min-width: 480px) {
  44 + .media-element {
  45 + //some attr
  46 + }
185 } 47 }
186 48
187 -## CSS引号  
188 -属性选择器或属性值用双引号(""),而不是单引号('')括起来。URI / URL不要使用引号。 49 +## 前缀属性
  50 +使用前缀属性时,通过缩进使取值垂直对齐。
189 51
190 //GOOD 52 //GOOD
191 - @import url(//cdn.com/foundation.css);  
192 -  
193 - html {  
194 - font-family: "open sans", arial, sans-serif;  
195 - }  
196 -  
197 - body:after {  
198 - content: "pause";  
199 - }  
200 -  
201 - //BAD  
202 - @import url('//cdn.com/foundation.css');  
203 -  
204 - html {  
205 - font-family: 'open sans', arial, sans-serif;  
206 - }  
207 -  
208 - body:after {  
209 - content: 'pause'; 53 + .selector {
  54 + -webkit-box-shadow: 0 1px 2px rgba(0,0,0,.5);
  55 + box-shadow: 0 1px 2px rgba(0,0,0,.5);
210 } 56 }
211 57
212 ----------------------------------------------------------------------- 58 -----------------------------------------------------------------------
213 -## SASS套规则 59 +## SASS
214 ### 选择器嵌套 60 ### 选择器嵌套
215 -在Sass中你可以嵌套选择器,这可以使代码变得更清洁和可读。嵌套所有的选择器,但尽量避免嵌套没有任何内容的选择器。如果你需要指定一些子元素的样式属性,而父元素将不使用什么样式属性,可以使用常规的CSS选择器链。 61 +避免不必要的嵌套。只有在需要给父元素增加样式并且有多个子元素时才考虑嵌套
216 62
217 //GOOD 63 //GOOD
218 .content { 64 .content {
@@ -239,112 +85,13 @@ CSS憬改 font 摮砲撠賢雿輻嚗雿 @@ -239,112 +85,13 @@ CSS憬改 font 摮砲撠賢雿輻嚗雿
239 //GOOD 85 //GOOD
240 .content { 86 .content {
241 display: block; 87 display: block;
242 - 88 + //SPACE HERE
243 > .news-article { 89 > .news-article {
244 background-color: #eee; 90 background-color: #eee;
245 -  
246 - > .title {  
247 - font-size: 1.2em;  
248 - }  
249 -  
250 - > .article-footnote {  
251 - font-size: 0.8em;  
252 - }  
253 - }  
254 - }  
255 -  
256 -### 上下文媒体查询  
257 -在Sass中,当你嵌套你的选择器时也可以使用上下文媒体查询,你可以在任何给定的嵌套层次中使用媒体查询。  
258 -  
259 - //GOOD  
260 - .content-page {  
261 - font-size: 1.2rem;  
262 -  
263 - @media screen and (min-width: 641px) {  
264 - font-size: 1rem;  
265 - }  
266 -  
267 - > .main {  
268 - background-color: whitesmoke;  
269 -  
270 - > .latest-news {  
271 - padding: 1rem;  
272 -  
273 - > .news-article {  
274 - padding: 1rem;  
275 -  
276 - > .title {  
277 - font-size: 2rem;  
278 -  
279 - @media screen and (min-width: 641px) {  
280 - font-size: 3rem;  
281 - }  
282 - }  
283 - }  
284 - }  
285 -  
286 - > .content {  
287 - margin-top: 2rem;  
288 - padding: 1rem;  
289 - }  
290 - }  
291 -  
292 - > .page-footer {  
293 - margin-top: 2rem;  
294 - font-size: 1rem;  
295 -  
296 - @media screen and (min-width: 641px) {  
297 - font-size: 0.8rem;  
298 - }  
299 - }  
300 - }  
301 -  
302 - //BAD  
303 - .content-page {  
304 - font-size: 1.2rem;  
305 -  
306 - > .main {  
307 - background-color: whitesmoke;  
308 -  
309 - > .latest-news {  
310 - padding: 1rem;  
311 -  
312 - > .news-article {  
313 - padding: 1rem;  
314 -  
315 - > .title {  
316 - font-size: 2rem;  
317 - }  
318 - }  
319 - }  
320 -  
321 - > .content {  
322 - margin-top: 2rem;  
323 - padding: 1rem;  
324 - }  
325 - }  
326 -  
327 - > .page-footer {  
328 - margin-top: 2rem;  
329 - font-size: 1rem;  
330 - }  
331 - }  
332 -  
333 - @media screen and (min-width: 641px) {  
334 - .content-page {  
335 - font-size: 1rem;  
336 -  
337 - > .main > .latest-news > .news-article > .title {  
338 - font-size: 3rem;  
339 - }  
340 -  
341 - > .page-footer {  
342 - font-size: 0.8rem;  
343 } 91 }
344 - }  
345 } 92 }
346 93
347 -### 嵌套顺序和父级选择器 94 +### 嵌套顺序
348 当使用Sass的嵌套功能的时候,重要的是有一个明确的嵌套顺序,以下内容是一个scss块应具有的顺序: 95 当使用Sass的嵌套功能的时候,重要的是有一个明确的嵌套顺序,以下内容是一个scss块应具有的顺序:
349 96
350 1. 当前选择器的样式属性 97 1. 当前选择器的样式属性
1 # HTML代码规范 1 # HTML代码规范
2 2
3 -## 文档类型  
4 -使用 HTML5 的文档类型声明: <!DOCTYPE html>。建议使用 text/html 格式的 HTML。避免使用 XHTML。XHTML 以及它的属性,比如 application/xhtml+xml 在浏览器中的应用支持与优化空间都十分有限。  
5 -  
6 -HTML 中最好不要将无内容元素的标签闭合,例如:使用 <br> 而非 <br />  
7 -  
8 -*ps:无内容元素标签包括:`area`,`base`, `br`, `col`, `command`, `embed`,` hr`, `img`, `input`, `keygen`, `link`, `meta`, `param`, `source`, `track`, `wbr`*  
9 -  
10 -## 语义化  
11 -根据元素(有时被错误地称作“标签”)被创造出来时的初始意义来使用它。打个比方,用heading元素来定义头部标题,p元素来定义文字段落,用a元素来定义链接锚点,等等。  
12 -有根据有目的地使用 HTML 元素,对于可访问性、代码重用、代码效率来说意义重大。  
13 -  
14 - //GOOD  
15 - <!-- The page header should go into a header element -->  
16 - <header>  
17 - <!-- As this title belongs to the page structure it's a heading and h1 should be used -->  
18 - <h1>My page title</h1>  
19 - </header>  
20 -  
21 - <!-- All navigation should go into a nav element -->  
22 - <nav class="top-navigation">  
23 - <!-- A listing of elements should always go to UL (OL for ordered listings) -->  
24 - <ul>  
25 - <li class="nav-item"><a href="#home">Home</a></li>  
26 - <li class="nav-item"><a href="#news">News</a></li>  
27 - <li class="nav-item"><a href="#about">About</a></li>  
28 - </ul>  
29 - </nav>  
30 -  
31 - <!-- The main part of the page should go into a main element (also use role="main" for accessibility) -->  
32 - <main class="news-page" role="main">  
33 - <!-- A section of a page should go into a section element. Divide a page into sections with semantic elements. -->  
34 - <section class="page-section news">  
35 - <!-- A section header should go into a section element -->  
36 - <header>  
37 - <!-- As a page section belongs to the page structure heading elements should be used (in this case h2) -->  
38 - <h2 class="title">All news articles</h2>  
39 - </header>  
40 -  
41 - <!-- If a section / module can be seen as an article (news article, blog entry, products teaser, any other  
42 - re-usable module / section that can occur multiple times on a page) a article element should be used -->  
43 - <article class="news-article">  
44 - <!-- An article can contain a header that contains the summary / introduction information of the article -->  
45 - <header>  
46 - <!-- As a article title does not belong to the overall page structure there should not be any heading tag! -->  
47 - <div class="article-title">Good article</div>  
48 - <!-- Small can optionally be used to reduce importance -->  
49 - <small class="intro">Introduction sub-title</small>  
50 - </header>  
51 -  
52 - <!-- For the main content in a section or article there is no semantic element -->  
53 - <div class="content">  
54 - <p>This is a good example for HTML semantics</p>  
55 - </div>  
56 - <!-- For content that is represented as side note or less important information in a given context use aside -->  
57 - <aside class="article-side-notes">  
58 - <p>I think I'm more on the side and should not receive the main credits</p>  
59 - </aside>  
60 - <!-- Articles can also contain footers. If you have footnotes for an article place them into a footer element -->  
61 - <footer class="article-foot-notes">  
62 - <!-- The time element can be used to annotate a timestamp. Use the datetime attribute to specify ISO time  
63 - while the actual text in the time element can also be more human readable / relative -->  
64 - <p>This article was created by David <time datetime="2014-01-01 00:00" class="time">1 month ago</time></p>  
65 - </footer>  
66 - </article>  
67 -  
68 - <!-- In a section, footnotes or similar information can also go into a footer element -->  
69 - <footer class="section-footer">  
70 - <p>Related sections: Events, Public holidays</p>  
71 - </footer>  
72 - </section>  
73 - </main>  
74 -  
75 - <!-- Your page footer should go into a global footer element -->  
76 - <footer class="page-footer">  
77 - Copyright 2014  
78 - </footer>  
79 -  
80 - //BAD  
81 - <b>My page title</b>  
82 - <div class="top-navigation">  
83 - <div class="nav-item"><a href="#home">Home</a></div>  
84 - <div class="nav-item"><a href="#news">News</a></div>  
85 - <div class="nav-item"><a href="#about">About</a></div>  
86 - </div>  
87 -  
88 - <div class="news-page">  
89 - <div class="page-section news">  
90 - <div class="title">All news articles</div>  
91 - <div class="news-article">  
92 - <h2>Bad article</h2>  
93 - <div class="intro">Introduction sub-title</div>  
94 - <div class="content">This is a very bad example for HTML semantics</div>  
95 - <div class="article-side-notes">I think I'm more on the side and should not receive the main credits</div>  
96 - <div class="article-foot-notes">  
97 - This article was created by David <div class="time">2014-01-01 00:00</div>  
98 - </div>  
99 - </div>  
100 -  
101 - <div class="section-footer">  
102 - Related sections: Events, Public holidays  
103 - </div>  
104 - </div>  
105 - </div>  
106 -  
107 - <div class="page-footer">  
108 - Copyright 2014  
109 - </div>  
110 -  
111 -## 多媒体回溯  
112 -对页面上的媒体而言,像图片、视频、canvas 动画等,要确保其有可替代的接入接口。图片文件我们可采用有意义的备选文本(alt),视频和音频文件我们可以为其加上说明文字或字幕。  
113 -  
114 - //GOOD  
115 - <img src="luke-skywalker.jpg" alt="Luke skywalker riding an alien horse">  
116 -  
117 - //BAD  
118 - <img src="luke-skywalker.jpg">  
119 -  
120 -## 关注点分离  
121 -严格地保证**结构HTML****表现CSS****行为JS**三者分离。  
122 -  
123 -清晰的分层意味着:  
124 - 不使用超过一到两张样式表  
125 - 不使用超过一到两个脚本(学会用合并脚本)  
126 - 不使用行内样式  
127 - 不在元素上使用 style 属性  
128 - 不使用行内脚本  
129 - 不使用表象元素(`b`, `u`, `center`, `font`, `b` ... )  
130 - 不使用表象 class 名(i.e. red, left, center)  
131 -  
132 - //GOOD  
133 - <!DOCTYPE html>  
134 - <html>  
135 - <head>  
136 - <!-- Concatinate your style sheets into a single one -->  
137 - <link rel="stylesheet" href="main.css">  
138 - </head>  
139 - <body>  
140 - <!-- Don't use style attributes but assign sensible classes and apply styles in the stylesheet -->  
141 - <h1 class="title"></h1>  
142 - <!-- Don't use presentational elements and assign sensible classes -->  
143 - <div class="sub-title">I'm a subtitle and I'm bold!</div>  
144 - <!-- Maybe your comments get centered in your presentation but that decision is up to the stylesheet -->  
145 - <span class="comment">Dare you center me!</span>  
146 - <!-- You wanted to make it red because it's important so then also name the class important and decide in the stylesheet  
147 - what you want to do with it -->  
148 - <div class="important">I'm important!</div>  
149 -  
150 - <!-- Put all your scripts into files and concatinate them into a single one -->  
151 - <script async src="main.js"></script>  
152 - </body>  
153 - </html>  
154 -  
155 -  
156 - //BAD  
157 - <!DOCTYPE html>  
158 - <html>  
159 - <head>  
160 - <link rel="stylesheet" href="base.css">  
161 - <link rel="stylesheet" href="grid.css">  
162 - <link rel="stylesheet" href="type.css">  
163 - <link rel="stylesheet" href="modules/teaser.css">  
164 - </head>  
165 - <body>  
166 - <h1 style="font-size: 3rem"></h1>  
167 - <b>I'm a subtitle and I'm bold!</b>  
168 - <center>Dare you center me!</center>  
169 - <script>  
170 - alert('Just dont...');  
171 - </script>  
172 - <div class="red">I'm important!</div>  
173 - </body>  
174 - </html>  
175 -  
176 -## HTML 内容至上  
177 -不要让非内容信息污染了你的HTML。HTML就应该只关注内容,HTML标签的目的,就是为了不断地展示内容信息。  
178 -  
179 -* 不要引入一些特定的 HTML 结构来解决一些视觉设计问题  
180 -* 不要将 img 元素当做专门用来做视觉设计的元素 3 +## HTML 引号
  4 +使用双引号(" ") 而不是单引号(' ') 。
181 5
182 - //GOOD  
183 - <!-- That's clean markup! -->  
184 - <span class="text-box">  
185 - See the square next to me?  
186 - </span> 6 +## 标签闭合
  7 +在自动闭合标签后不要使用斜线`/`
187 8
188 - /* We use a :before pseudo element to solve the design problem of placing a colored square in front of the text content */  
189 - .text-box:before {  
190 - content: "";  
191 - display: inline-block;  
192 - width: 1rem;  
193 - height: 1rem;  
194 - background-color: red;  
195 - } 9 +## 属性顺序
  10 +HTML属性应该按照特定顺序出现在标签内
196 11
197 - //BAD  
198 - <!-- We should not introduce an additional element just to solve a design problem -->  
199 - <span class="text-box">  
200 - <span class="square"></span>  
201 - See the square next to me?  
202 - </span> 12 +* id
  13 +* class
  14 +* name
  15 +* data-
  16 +* src, for, type, href
  17 +* title, alt
  18 +* aria-*, role
203 19
204 - .text-box > .square {  
205 - display: inline-block;  
206 - width: 1rem;  
207 - height: 1rem;  
208 - background-color: red;  
209 - } 20 +## boolean属性
  21 +不需要为boolean属性添加取值,存在表示true,不存在则表示false。比如:selected,disabled等。
210 22
211 -图片和SVG能被引入到HTML中的唯一理由是它们呈现出了与内容相关的一些信息。 23 +## 减少不必要的标签嵌套
212 24
213 //GOOD 25 //GOOD
214 - <!-- That's clean markup! -->  
215 - <span class="text-box">  
216 - See the square next to me?  
217 - </span>  
218 -  
219 - /* We use a :before pseudo element with a background image to solve the problem */  
220 - .text-box:before {  
221 - content: "";  
222 - display: inline-block;  
223 - width: 1rem;  
224 - height: 1rem;  
225 - background: url(square.svg) no-repeat;  
226 - background-size: 100%;  
227 - } 26 + <img class="avatar" src="..." alt="...">
228 27
229 //BAD 28 //BAD
230 - <!-- Content images should never be used for design elements! -->  
231 - <span class="text-box">  
232 - <img src="square.svg" alt="Square" />  
233 - See the square next to me? 29 + <span class="avatar">
  30 + <img src="..." alt="...">
234 </span> 31 </span>
235 32
236 -## type属性  
237 -省略样式表与脚本上的type属性。鉴于HTML5中以上两者默认的type值就是text/css和text/javascript,所以type属性一般是可以忽略掉的。甚至在老旧版本的浏览器中这么做也是安全可靠的。  
238 -  
239 - //GOOD  
240 - <link rel="stylesheet" href="main.css">  
241 - <script src="main.js"></script>  
242 -  
243 - //BAD  
244 - <link rel="stylesheet" href="main.css" type="text/css">  
245 - <script src="main.js" type="text/javascript"></script>  
246 -  
247 -## 格式化规则  
248 -在每一个块状元素,列表元素和表格元素后,加上一新空白行,并对其子孙元素进行缩进。内联元素写在一行内,块状元素还有列表和表格要另起一行。  
249 -  
250 - //GOOD  
251 - <blockquote>  
252 - <p><em>Space</em>, the final frontier.</p>  
253 - </blockquote>  
254 -  
255 - <ul>  
256 - <li>Moe</li>  
257 - <li>Larry</li>  
258 - <li>Curly</li>  
259 - </ul>  
260 -  
261 - <table>  
262 - <thead>  
263 - <tr>  
264 - <th scope="col">Income</th>  
265 - <th scope="col">Taxes</th>  
266 - </tr>  
267 - </thead>  
268 - <tbody>  
269 - <tr>  
270 - <td>$ 5.00</td>  
271 - <td>$ 4.50</td>  
272 - </tr>  
273 - </tbody>  
274 - </table>  
275 -  
276 -## HTML 引号  
277 -使用双引号(" ") 而不是单引号(' ') 。 33 +## class和id命名
  34 +* 保持小写以及中划线`-`分隔
  35 +* 命名简短但是也要明确指示角色和意图
  36 +* 必要时可以使用父节点的class作为前缀
278 37
279 38
280 -[参考](http://www.css88.com/archives/5364)  
  39 +[参考资料1](http://alloyteam.github.io/code-guide/#html)
  40 +[参考资料2](http://www.css88.com/archives/5364)
1 # 通用代码规范 1 # 通用代码规范
2 2
3 ## 文件/资源命名 3 ## 文件/资源命名
4 -在 web 项目中,所有的文件名应该都遵循同一命名约定。以可读性而言,减号`-`是用来分隔文件名的不二之选。同时它也是常见的 URL 分隔符(i.e. //example.com/blog/my-blog-entry or //s.example.com/images/big-black-background.jpg),所以理所当然的,减号应该也是用来分隔资源名称的好选择 4 +文件,资源,目录等全部**小写**命名,有多个单词组成时以中划线`-`分隔;有复数结构时,采用复数命名
5 5
6 -**请确保文件命名总是以字母开头而不是数字**。而以特殊字符开头命名的文件,一般都有特殊的含义与用处(比如compass中的下划线就是用来标记跳过直接编译的文件用的)。  
7 -  
8 -**资源的字母名称必须全为小写**,这是因为在某些对大小写字母敏感的操作系统中,当文件通过工具压缩混淆后,或者人为修改过后,大小写不同而导致引用文件不同的错误,很难被发现。  
9 -  
10 -还有一些情况下,需要对文件增加前后缀或特定的扩展名(比如 .min.js, .min.css),抑或一串前缀(比如 3fa89b.main.min.css)。这种情况下,建议使用**点分隔符**来区分这些在文件名中带有清晰意义的元数据。 6 +对于压缩文件等有需要特殊前缀的文件使用点`.`进行划分,比如a.min.js。
11 7
12 //GOOD 8 //GOOD
13 my-script.js 9 my-script.js
@@ -23,28 +19,11 @@ @@ -23,28 +19,11 @@
23 1001-scripts.js 19 1001-scripts.js
24 my-file-min.css 20 my-file-min.css
25 21
26 -## 协议  
27 -不要指定引入资源所带的具体协议。当引入样式和脚本,图片或其他媒体文件时,URL所指向的具体路径,不要指定协议部分(http:,https:),除非这两者协议都不可用。不指定协议使得 URL 从绝对的获取路径转变为相对的,在请求资源协议无法确定时非常好用,而且还能为文件大小节省几个字节。  
28 -  
29 - //GOOD  
30 - <script src="//cdn.com/foundation.min.js"></script>  
31 - //  
32 - .example {  
33 - background: url(//static.example.com/images/bg.jpg);  
34 - }  
35 -  
36 - //BAD  
37 - <script src="http://cdn.com/foundation.min.js"></script>  
38 - //  
39 - .example {  
40 - background: url(http://static.example.com/images/bg.jpg);  
41 - }  
42 -  
43 ## 文本缩进 22 ## 文本缩进
44 一次缩进4个空格 23 一次缩进4个空格
45 24
46 ## 注释 25 ## 注释
47 -原则:**适量,并且切中要害*** 26 +原则:**适量,并且切中要害**
48 必要的注释使用场景 27 必要的注释使用场景
49 1. 代码晦涩难懂 28 1. 代码晦涩难懂
50 2. 可能被别人误认为是错误的代码 29 2. 可能被别人误认为是错误的代码
@@ -59,4 +38,5 @@ NOTE:大段的代码注释尽量予以避免,N久后,那段代码的存在 @@ -59,4 +38,5 @@ NOTE:大段的代码注释尽量予以避免,N久后,那段代码的存在
59 对于 JavaScript的代码检查,建议使用*JSHint*。(sublime Text中可以安装jshint插件) 38 对于 JavaScript的代码检查,建议使用*JSHint*。(sublime Text中可以安装jshint插件)
60 39
61 40
62 -[参考资料](http://www.css88.com/archives/5361)  
  41 +[参考资料1](http://www.css88.com/archives/5361)
  42 +[参考资料2](http://alloyteam.github.io/code-guide/)