微信分享 Logo

编码规范说明

QMUI 本身的代码遵循一系列的规范编写,这是由于 Web UI 代码(CSS 与 HTML 为主)语法较为松散,引入编码规范有助于提高团队内协助的效率以及代码的可维护性。

HTML/CSS 编写规范

为最大限度解决协同合作过程中出现的命名冲突问题、方便理解代码上下文、提高代码的执行效率,同时缩短项目交接时间、有必要制定一套简单易用的命名规范。基本原则是 class 需要遵循其代表的功能语义,模块化开发,不同业务模块使用不同前缀,公共部门使用项目缩写为前缀。

前缀规范

  1. 公共组件命名以项目缩写作为前缀,如一个名为 Demo 的项目,项目缩写可以是 dm,那么该项目下的项目组件和公共类可以这样命名: dm_btn(按钮)、dm_icon(图标)、dm_ipt(输入框)、dm_toolbar(工具栏)。
  2. 逻辑模块命名以具体描述作为前缀,如简历(resume)功能里面的非公共组件部分,以 resume_ 作为前缀(resume_mod、resume_text、resume_list),个人信息(profile)页面的非公共组件部分,则可以以 profile_ 作为前缀(profile_statge、profile_stage_title)。

格式规范

  1. 允许出现下划线和驼峰(大小写)。
  2. 除用于表示前缀的下划线外,其余下划线只有两种意义,一种代表直接父子关系,一种代表扩展关系。
  3. 下划线后面紧跟小写,代表直接父子关系,如:
    <div class="dm_toolbar"> <div class="dm_toolbar_header"> <div class="dm_toolbar_header_title"></div> </div> </div> <div class="resume_mod"> <div class="resume_mod_header"></div> <div class="resume_mod_footer"></div> </div>
    对应的 CSS 选择器格式:
    .dm_toolbar { ... } .dm_toolbar_header { ... } .dm_toolbar_header_title { ... } .resume_mod { ... } .resume_mod_header { ... } .resume_mod_footer { ... }
  4. 下划线后面紧跟大写,代表扩展关系,如:
    <a href="javascript:;" class="dm_btn"></a> <a href="javascript:;" class="dm_btn dm_btn_Big"></a> <div class="resume_mod resume_mod_List"> <div class="resume_mod_cnt"></div> </div>
    对应的CSS选择器格式:
    .dm_btn { ... } .dm_btn_Big { ... } .resume_mod { ... } .resume_mod_List { ... } .resume_mod_cnt { ... } .resume_mod_List .resume_mod_cnt { ... }
  5. 若一个样式名由多个单词组成,则从第二个单词起,每个单词的第一个字母大写,如:
    <div class="resume_txtErrWrap"></div>

SCSS/CSS 文件注释规范

CSS 注释按照等级划分,包括文件级注释、模块级注释、行内级注释3种。注释的目的是让代码阅读者了解到代码本身所不能表达的信息,关键在于“why”,尽量避免“how”,因为如何实现是看代码即可明白的,不需要多此一举(除非实现方式难以看懂),而为什么这么实现就需要注释写明了。 注释的原则是表达清晰,让人一言既明为什么这么做、如何使用。

注释的格式

单行注释,以“/* */”包裹注释内容,注意内容与注释符之间有头尾的空格隔开。例如:
正确示范:/* 注释内容 */ 错误示范:/*注释内容和注释符头尾要有空格*/
多行注释,以“/**”开头,紧接着换行符。从第二行开始,每一行的开头都是“空格”+“*”+“空格”,最后一行以“空格”+“*”+“/”结尾。 如有必要,用“@”+关键词+“空格”注明关键信息。例如:
正确示范: /** * 注释内容 * @author xxx<xxx@tencent.com> */ 错误示范: /* 注释符第一行应该是“/**”,每一行开头是“* ” */ /** *每一行注释内容与开头的“*”之间要有空格 */ /** * 注释符结尾只需要“*/”即可 **/

文件级注释

对于文件而言,最关键的信息在于代码维护者是谁?这份文件是什么时候的版本?文件内容包含什么? 因此推荐的注释模板如下:
/** * ftnlist.css 中转站列表的样式文件,同时也用于写信超大附件的文件列表样式 * @author molice * @date 2014-08-27 * * #reset * * #layout 主框架布局 * #list 文件列表 * #function 公共方法函数 * #... */ /* #reset */ body { font-size: 14px; } ...
上述推荐模板中,在文件头注释里用“#”列出了当前文件的内容结构,在某个代码段开始处又注明了当前代码段的“#”标志,从而实现类似于文件目录的形式。 为什么使用“#”来标志,一方面是“#”在url内属于hash部分,本身是用来做锚点定位的,其次vim默认配置里,当使用“#”或“*”快捷键搜索当前光标所处的单词时,“#”能和字母一起被识别为一个完整单词,这样整个文件里某个“#”标志只可能出现两次:一次在文件头目录内,一次在实际代码段位置开头。这样就能实现目录搜索定位功能了。

模块级注释

当某个模块有较多分类/拓展的情况,需要一定的说明才能正确使用时,推荐为它加上模块级注释。 模块级注释类似面向对象编程里对某个类进行注释,说明它的作用、使用时有什么依赖、提供哪些方法、class如何嵌套。 以下是一个推荐模板:
/** * .qm_list_item * + .qm_list_item_BorderNone 不显示item底部的分隔线 * + .qm_list_item_Accessory 在item右边显示向右箭头 * + .qm_list_item_Style2 标题、副标题上下排列 * * > [.qm_list_item_control] 可选。在列表左边显示一个控制控件,例如checkbox、radio等 * > .qm_list_item_content 包裹item内容的容器 * > [.qm_list_item_icon] 可选。在内容左边显示一个图片 * > .qm_list_item_textWrapper 包裹item文字内容的容器,内部只能摆放文字 * > .qm_list_item_title item的标题,默认为黑色 * > .qm_list_item_subtitle item的副标题,默认会灰色 * */ .qm_list_item { ... border-bottom:1px solid #000; ... } .qm_list_item_BorderNone { border-bottom:none; }
其中第一行指明当前模块的名称,一般以根className命名。 从第二行开始,用相邻选择器“+”表示与根className同级的className,一般是一些当前模块的拓展选项。例如模块默认带底部边框线,但又提供一个拓展选项“.qm_list_item_BorderNone”可以在需要时去掉底部边框线。 若要表达“父-子”嵌套的关系,则缩进两个空格,用后代选择器“>”引出子级className。例如上述模板表达了使用模块时html结构应该如何嵌套:
<div class="qm_list_item"> <div class="qm_list_item_control">这个节点可选,所以注释里用中括号“[]”包起来</div> <div class="qm_list_item_content"> <div class="qm_list_item_textWrapper"> <div class="qm_list_item_title">这个节点必须放在textWrapper内,所以注释里有缩进和“>”关系</div> <div class="qm_list_item_subtitle"></div> </div> </div> </div>

行内注释

当某句语句比较特殊,或实现方式与标准的实现方式不同,为了避免阅读时产生疑惑,就必须为语句添加说明。 行内注释紧跟写在需要注释的语句的后面,语句和注释之间不需要有空格。行内注释以“/* ”开始,以“ */”结束。注意开头、结尾均有空格隔开注释内容。
.layout_left { float: left; margin-right: 10px; } .layout_right { overflow: hidden; /* 产生BFC,隔开左右两部分内容 */ }