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

概述

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

命名规范

此规范为图片命名规范，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 (you@example.org)
 * @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<qinbinyang@zuijiao.net>
 */

2. css注释的写法：

/* Footer */

内容区

/* End Footer */

关注点分离

理解 web 中如何和为什么区分不一样的关注点，这很重要。这里的关注点主要指的是：信息（HTML 结构）、外观（CSS）和行为（JavaScript）。为了使它们成为可维护的干净整洁的代码，咱们要尽量的将它们分离开来。
严格地保证结构、表现、行为三者分离，并尽可能使三者之间没有太多的交互和联系。
就是说，尽可能在文档和模板中只包含结构性的 HTML；而将全部表现代码，移入样式表中；将全部动做行为，移入脚本之中。
在此以外，为使得它们之间的联系尽量的小，在文档和模板中也尽可能少地引入样式和脚本文件。
清晰的分层意味着：
不使用超过一到两张样式表i.e. main.css, vendor.css
不使用超过一到两个脚本（学会用合并脚本）
不使用行内样式<style>.no-good {}</style>
不在元素上使用 style 属性<hr style="border-top: 5px solid black">
不使用行内脚本<script>alert('no good')</script>
不使用表象元素i.e. <b>, <u>, <center>, <font>, <b>
不使用表象 class 名red, left, center

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