开发规范（二）命名规范及注释规范

概述

为提高团队协作效率，规范文件管理，方便项目后期维护，提高代码质量，特制订此文档，前端开发人员必须遵照本规范进行前台页面开发。

命名规范

此规范为图片命名规范，html、css文件命名规范请参照 开发规范（一）目录规范

图片的名称分为头尾两部分，用减号-隔开，头部分表示此图片的大类性质

banner-* //放置在页面顶部的广告、装饰图案等长方形的图片
logo-*   //标志性的图片
btn-*-*  //在页面上位置不固定并且带有链接的小图片；命名规范：btn-功能名-大小/私有
pic-*    //装饰用的照片
tit-*    //不带链接表示标题的图片
icon-*   //一系列图标图片

鼠标感应效果：图片名+on/off；例如：icon-list-on.png,icon-list-off.png

文本缩进

（重要）统一使用 2 个空格缩进，不得使用 tab 和 4 个空格

注释

重中之重，已加入绩效考核指标
更新代码后即时更新注释
注释是你自己与你的小伙伴们了解代码写法和目的的唯一途径。特别是在写一些看似琐碎的无关紧要的代码时，由于记忆点不深刻，注释就变得尤为重要了。

当你写注释时一定要注意：不要写你的代码都干了些什么，而要写你的代码为什么要这么写，背后的考量是什么。当然也可以加入所思考问题或是解决方案的链接地址。

1. 在文件开始时写块注释：

/** 
 * 作用于哪些页面
 * 注明代码业务/功能说明
 * @authors Your Name ([email protected])
 * @date    2016-05-16
 * @version $Id$
 */

// 单行注释添加一个空格

var offset = 0; // 此处注明变量注释

if(includeLabels) {
  // If the labels are included we need to have a minimum offset of 20 pixels
  // We need to set it explicitly because of the following bug: 
  // http://somebrowservendor.com/issue-tracker/ISSUE-1
  offset = 20;
}

模块功能描述说明

/**
 * ------------------------------------------------------------------
 * 模块描述说明
 * ------------------------------------------------------------------
 */

模块内的小函数方法归类：

/**
 * 小函数方法归类说明，这些零散的小函数方法放在一起 对应 一个业务方法逻辑
 * ------------------------------------------------------------------
 */

单个函数注释

/**
 * 函数功能简述
 *
 * 具体描述一些细节
 *
 * @param    {string}  address     地址
 * @param    {array}   com         商品数组
 * @param    {string}  pay_status  支付方式
 * @returns  void
 *
 * @date     2014-04-12
 * @author   QETHAN
 */

2. css注释的写法：

/* Footer */

内容区

/* End Footer */

关注点分离

理解 web 中如何和为何区分不同的关注点，这很重要。这里的关注点主要指的是：信息（HTML 结构）、外观（CSS）和行为（JavaScript）。为了使它们成为可维护的干净整洁的代码，我们要尽可能的将它们分离开来。
严格地保证结构、表现、行为三者分离，并尽量使三者之间没有太多的交互和联系。
就是说，尽量在文档和模板中只包含结构性的 HTML；而将所有表现代码，移入样式表中；将所有动作行为，移入脚本之中。
在此之外，为使得它们之间的联系尽可能的小，在文档和模板中也尽量少地引入样式和脚本文件。
清晰的分层意味着：
不使用超过一到两张样式表i.e. main.css, vendor.css
不使用超过一到两个脚本（学会用合并脚本）
不使用行内样式
不在元素上使用 style 属性

---

不使用行内脚本
不使用表象元素i.e. , , , ,
不使用表象 class 名red, left, center

部分内容来自：强迫症->js注释规范