以下文档将概述一个合理的CSS开发风格指导。本指导文件强烈鼓励开发者使用已经存在了的、常见的、合力的文风。您应该有选择地吸纳一些内容来创造您自己的风格指南。
这个文档将持续更新,欢迎提出新的想法。还请多多贡献。
Principles of writing consistent, idiomatic CSS(原版)
目录
- 通用原则
- 空格
- 注释
- 格式
- 命名
- 实例
- 代码组织
- 构建及部署
1. 通用原则
“作为成功的项目的一员,很重要的一点是意识到只为自己写代码是很糟糕的行为。如果将有成千上万人使用你的代码, 那么你需要编写最具明确性的代码,而不是以自我的喜好来彰显自己的智商。” – Idan Gazit
- 别想着过早地优化代码。先得保证它们可读又可理解才行。
- 在任何代码库中,无论有多少人参与及贡献,所有代码都应该如同一个人编写的一样。
- 严格执行一致认可的风格。
- 如果有疑议,则使用现有的、通用的模式。
2. 空格
在项目的所有代码中,应该只有一个风格。在空格的使用上,必须始终保持一致。使用空格来提高可读性。
- 永远不要在缩进时混用空格和制表符(又称TAB符号)。
- 在软缩进(使用空格)和真正的制表符间选择其一,并始终坚持这一选择。(推荐使用空格)
- 如果使用空格进行缩进,选择每个缩进所使用的空格数。(推荐:4个空格)
提示:将编辑器配置为“显示不可见内容”。这使你可以清除行尾的空格和不需要缩进的空行里的空格,同时可以避免对注释的污染。
提示:确定好一种空格格式后,您可以用一个EditorConfig文件(或者其他相同的东西)来帮助在代码库之间维持这种基本的空格约定。
3. 注释
良好的注释是非常重要的。请留出时间来描述组件(component)的工作方式、局限性和构建它们的方法。不要让你的团队其它成员 来猜测一段不通用或不明显的代码的目的。
注释的风格应当简洁,并在代码库中保持统一。
- 将注释放在主题上方并独占一行。
- 控制每行长度在合理的范围内,比如80个字符。
- 使用注释从字面上将CSS代码分隔为独立的部分。
- 注释的大小写应当与普通句子相同,并且使用一致的文本缩进。
提示:通过配置编辑器,可以提供快捷键来输出一致认可的注释模式。
CSS示例:
4. 格式
最终选择的代码风格必须保证:易于阅读,易于清晰地注释,最小化无意中引入错误的可能性,可生成有用的diff和blame。
- 在多个选择器的规则集中,每个单独的选择器独占一行。
- 在规则集的左大括号前保留一个空格。
- 在声明块中,每个声明独占一行。
- 每个声明前保留一级缩进。
- 每个声明的冒号后保留一个空格。
- 对于声明块的最后一个声明,始终保留结束的分号。
- 规则集的右大括号保持与该规则集的第一个字符在同一列。
- 每个规则集之间保留一个空行。
样式声明的顺序应当遵守一个单一的原则。我的倾向是将相关的属性组合在一起,并且将对结构来说比较重要的属性(如定位或者盒模型) 放在前面,先于排版、背景及颜色等属性。
小型的开发团体,可能会想要把相关的属性声明(比如说定位和箱模型)摆在一起。
例外及细微偏移原则的情况
对于大量仅包含单条声明的声明块,可以使用一种略微不同的单行格式。在这种情况下,在左大括号之后及右大括号之前都应该保留一个空格。
- 在十六进制值中,使用小写,如
#aaa
。 - 单引号或双引号的选择保持一致。推荐使用双引号,如
content: ""
。 - 对于选择器中的属性值也加上引号,如
input[type="checkbox"]
。 - 如果可以的话,不要给0加上单位, 如
margin: 0
。
预处理:格式方面额外的考虑
不同的CSS预处理有着不同的特性、功能以及语法。编码习惯应当根据使用的预处理程序进行扩展,以适应其特有的功能。推荐在使用SCSS时遵守以下指导。
- 将嵌套深度限制在1级。对于超过2级的嵌套,给予重新评估。这可以避免出现过于详实的CSS选择器。
- 避免大量的嵌套规则。当可读性受到影响时,将之打断。推荐避免出现多于20行的嵌套规则出现。
- 始终将
@extend
语句放在声明块的第一行。 - 如果可以的话,将
@include
语句放在声明块的顶部,紧接着@extend
语句的位置。 - 考虑在自定义函数的名字前加上
x-
或其它形式的前缀。这有助于避免将自己的函数和CSS的原生函数混淆,或函数命名与库函数冲突。
5. 命名
不要试着把自己当作编译器或者预处理器,因此命名的时候尽量采用清晰的、有意义的名字。另外,对于 html文件和css文件中的代码,尽量采用一致的命名规则。
6. 实例
下面是含有上述约定的示例代码:
.cell
children. * * 1. Remove inter-cell whitespace * 2. Prevent inline-block cells wrapping / .grid { height: 100%; font-size: 0; / 1 / white-space: nowrap; / 2 / } /* * Grid cells * * No explicit width by default. Extend with .cell-n
classes. * * 1. Set the inter-cell spacing * 2. Reset white-space inherited from .grid
* 3. Reset font-size inherited from .grid
/ .cell { position: relative; display: inline-block; overflow: hidden; box-sizing: border-box; height: 100%; padding: 0 10px; / 1 / border: 2px solid #333; vertical-align: top; white-space: normal; / 2 / font-size: 16px; / 3 / } / Cell states / .cell.is-animating { background-color: #fffdec; } / Cell dimensions ====================================================================== / .cell-1 { width: 10%; } .cell-2 { width: 20%; } .cell-3 { width: 30%; } .cell-4 { width: 40%; } .cell-5 { width: 50%; } / Cell modifiers ======================================================================== */ .cell--detail, .cell--important { border-width: 4px; }
7. 代码组织
对于css代码库来说,如何组织代码文件是很重要的,尤其对于那些很大的代码库显得更加重要。这里介绍 几个组织代码的建议:
- 逻辑上对不同的代码进行分离。
- 不同的组件(component)的css尽量用不同的css文件(可以在build阶段用工具合并到一起)
- 如果用到了预处理器(比如less),把一些公共的样式代码抽象成变量,例如颜色,字体等等。
8. 构建及部署
任何一个项目,都应该有一个build的过程,在这个阶段我们可以通过工具对代码进行检测,测试,压缩等等,还 可以为生产环境准备好带有版本号的代码。在这里我推荐一下grunt这个工具,我感觉它很不错。
9. 转载
https://github.com/necolas/idiomatic-css/tree/master/translations/zh-CN
未经允许不得转载:空洽网 » 编写如一、符合习惯的CSS的原则