前端规范(1)---基本规范

前端规范—基本规范

1、文件规范

• html, css, js, images文件均归档至<系统开发规范>约定的目录中;

• html文件命名: 英文命名, 后缀.html. 同时将对应界面稿放于同目录中, 若界面稿命名为中文, 请重命名与html文件同名, 以方便后端添加功能时查找对应页面;

• css文件命名: 英文命名, 后缀.css 共用base.css, 首页index.css, 其他页面依实际模块需求命名;

• Js文件命名: 英文命名, 后缀.js. 共用common.js, 其他依实际模块需求命名.

2、html书写规范

• 需要为html元素添加自定义属性的时候, 首先要考虑下有没有默认的已有的合适标签去设置, 如果没有, 可以使用须以”data-“为前缀来添加自定义属性，避免使用”data:”等其他命名方式;
• 重要图片必须加上alt属性; 给重要的元素和截断的元素加上title;
• 特殊符号使用: 尽可能使用代码替代: 比如 <(<) & >(>) & 空格( ) & ?(?) 等等;

3、css书写规范

• 编码统一为utf-8;

• 为JavaScript预留钩子的命名, 请以 js_ 起始, 比如: js_hide, js_show;

• 规避class和id同名：

  a. 通过从属写法规避 如：#mainnav .firstnav{...}

  <div id="mainnav">
  <div class="firstnav">...</div>
  </div>

  b.通过父级元素id/class命名部分命名 main_firstnav{......}

  <div id="mainnav">
  <div class="main_firstnav">...</div>
  </div>

• css属性书写顺序；

  布局定位属性:margin padding float postion display visibility overflow

  自身属性: width height background border

  文本属性: font color text-align text-decoration text-indent

  其他属性: list-style vertical-vlign cursor z-index(层叠顺序) zoom

• 避免兼容性属性的使用，比如text-shadow || css3的相关属性；

• 减少使用影响性能的属性，比如position: absolute || float;

• 必须为大区块样式添加注释, 小区块适量注释;

• 代码缩进与格式, 建议单行书写;

4、JavaScript书写规范

• 变量命名：

  a.原生JavaScript变量要求是纯英文字母, 首字母须小写, 如iXueXi;

  b.jquery变量要求首字符为下划线_‘，如_iXueXi ;

• 类命名：首字母大写，驼峰式命名，如 IXueXi;

• 函数命名：首字母小写，驼峰式命名，如 iXueXi()
• 命名语义化, 尽可能利用英文单词或其缩写;
• 尽量避免使用存在兼容性及消耗资源的方法或属性, 比如eval() & innerText;
• 后期优化中, JavaScript非注释类中文字符须转换成unicode编码使用, 以避免编码错误时乱码显示;
• 代码结构明了, 加适量注释. 提高函数重用率;

5、图片规范

• 图片格式仅限于gif || png || jpg;
• 命名全部用小写英文字母 || 数字 || _ 的组合，其中不得包含汉字 || 空格 || 特殊字符；尽量用易懂的词汇, 便于团队其他成员理解; 另, 命名分头尾两部分, 用下划线隔开, 比如ad_left01.gif || btn_submit.gif;
• 尽量避免使用半透明的png图片(若使用, 请参考css规范相关说明)
• 运用css sprite技术集中小的背景图或图标, 减小页面http请求；

6、文件命名规范

统一用小写的英文字母，数字和下划线的组合，不得包含汉字空格和特殊字符。

子页面命名：

• 首页—index

• 产品列表—prolist 产品详情页面—prodetail

• 新闻列表—newslist 新闻详情页面—newsdetail

• 发展历史—history
• 关于我们—aboutus
• 联系我们—linkus,contactus

图片命名：

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

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

7、注释规范—尽量用英文来描述

用处：

• 难于理解的代码段
• 可能存在错误的代码段
• 浏览器特殊的HACK代码
• 想吐槽的产品逻辑, 合作同事
• 业务逻辑强相关的代码

单行注释

• 双斜线后，必须跟注释内容保留一个空格

• 可独占一行, 前边不许有空行, 缩进与下一行代码保持一致

• 可位于一个代码行的末尾，注意这里的格式

  // Good
  if (condition) {
  
     // if you made it here, then all security checks passed
     allowed();
  }
  
  var zhangsan = "zhangsan";    // 双斜线距离分号四个空格，双斜线后始终保留一个空格

多行注释

• 最少三行

• 前边留空一行

  /*
  * 注释内容与星标前保留一个空格
  */

文件注释

/*
 *@author: who are you
 *@date: when you write it
 *@description: the function of this file.
 */

多人合作注释

同一个文件的代码可能被多个人修改，这个时候需要标识出谁改了哪些部分

格式：// add begin by author ; Reason

​ // add end

// add begin by Liuxing ; Init post's id
var postId = 1;
// end add

// add begin by Liuxing
/**
 * 多行注释来说明原因
 */
var postId = 1;
// end add 

Javascript注释

/**
 * here boy, look here , here is girl
 * @method lookGril
 * @param {Object} balabalabala
 * @return {Object} balabalabala
 */

常用tag

@author、@callback、@copyright、@default、@deprecated、@throws 、@todo、@param、@returns

方法与函数的注释

/**
 * Converts text to some completely different text.
 * @param {string} arg1 An argument that makes this more interesting.
 * @return {string} Some return value.
 */
project.MyClass.prototype.someMethod = function(arg1) {
  // ...
};

属性注释

/**
 * Maximum number of things per pane.
 * @type {number}
 */
project.MyClass.prototype.someProperty = 4;

枚举

**
 * Enum for tri-state values.
 * @enum {number}
 */
project.TriState = {
  TRUE: 1,
  FALSE: -1,
  MAYBE: 0
};

/**
 * Sets project state.
 * @param {project.TriState} state New project state.
 */
project.setState = function(state) {
  // ...
};

Typedefs

/**
 * @param {string} tagName
 * @param {(string|Element|Text|Array.<Element>|Array.<Text>)} contents
 * @return {Element}
 */
goog.createElement = function(tagName, contents) {
  ...
};