Brix Style 开发规范

追求目标

清晰

代码结构和命名都要尽量清晰明了, 做到“观其貌, 知其意”

健壮

能处理常规意外情况. 不能处理的, 也要尽量在内部将意外catch住, 避免单点故障, 影响页面其他部分

灵活

能适应同种业务场景的不同表现类型, 但也不要为了灵活而增加太多的嵌套或配置参数

组件/模块尽量独立, 高自我保持性, 可以任意移动, 灵活组合

命名

命名方式

统一使用“组件/模块名 + 实例名 + 实例状态名”的命名方式如:

<span class="icon icon-ok icon-ok-disable"></span>

其中 icon 为模块名，icon-ok 为具体实例名，icon-ok-disable 为实例状态名

注：请不要偷懒写成

<span class="icon icon-ok-disable"></span>

命名单词与单词之间用连字符 - 分割，通常2到3级为宜，超过4级的，请以清晰的方式进行简化（样式表选择器层级数量与此相同）

命名的每个单词统一英文全拼，尽量不要缩写。必要情况下，缩写也要清晰明了并遵从预定俗成的缩写方式， 如可以将 .button 缩写成 .btn 而不要将 .icon 缩写成 .i 。实在无法英文表达的命名, 使用拼音全拼。

id、class

id 和 class 名称中只能出现小写的26个英文字母、数字和连字符（-），任何其它字符都严禁出现。

id 和 class 尽量用英文单词命名。确实找不到合适的单词时，可以考虑使用产品的中文拼音，比如 wangwang、dating。 对于中国以及淘宝特色词汇，也可以使用拼音，比如 xiaobao、 daigou。除了产品名称和特色词汇，其它任何情况下都严禁使用拼音。

JavaScript hook

仅在 JavaScript 中当作 hook 用的 id 和 class，命名规则为 J_UpperCamelCase（请注意，J_ 后的首字母也大写！），其中字母 J 代表 JavaScript， 也是钩子（hook）的象形。注意：如果在JavaScript和CSS中都需要用到，则不用遵守本约定。

自动化测试脚本中的 hook

在自动化测试脚本中当作 hook 用的 class，命名规则为 T_UpperCamelCase，其中字母 T 代表 Test。

父子节点状态简化

虽然要尽量模块独立，但考虑通常习惯，在可以简化程序开销的情况下，适当做兼容性妥协。

如一个包含 icon 的 button，写成结构：

<span class="button button-ok">
    <i class="icon icon-ok"><i>
</span>

这时候，如果 button 需要切换到 disable 禁用状态，除了在 span 上添加 button-ok-disable 还要在内部的 i 上添加 icon-ok-disable，多了一步操作 不喜欢的话，可以按照通常的做法，写成：

<span class="button button-ok button-ok-disable">
    <i class="icon"></i>
</span>

在 button 内部第一个空 icon，通过父级的 className 控制内部展示状态，但同时，也要能支持第一种写法。

代码风格

CSS

不能百分百保证一个页面上只出现一次的组件、模块，请使用 class 而不是 id 命名做选择器。

样式表中尽量避免出现标签选择器，使 html 更灵活。

缩进

html 文件按照 dom 结构层级进行换行和缩进，js 文件避免出现过长单行语句，换行、缩进、空格等和 css 文件一样，遵守“C风格”。

其他

浏览器支持标准

• A－高品质。严格按照设计师的交互行为和视觉品质
• B－中品质。支持体验降级，但仍旧需要保证统一的风格和品质
• C－低品质。页面在此级别浏览器下基本可用即可

z-index 约定

• 普通应用：1 - 999
• 悬浮菜单：1000 - 4999
• 模态窗口：5000 - 9999

文件格式

代码文件统一使用无 bom utf-8 编码保存

注释

注释要更多地体现为什么，而不是用来说明会怎么样

不建议的注释：

.btn:hover {
    display: none; /* 隐藏元素 */
}

建议的注释：

.btn:hover {
    display: none; /* 鼠标悬停时隐藏文本内容，防止溢出破坏结构 */
}

Less is More

像兼容的圆角、阴影、css 动画或公用的颜色，距离值等可以用 less 简化代码、提高效率的地方。