通用约定
文件与目录命名
- 一律小写, 必须是英文单词或产品名称的拼音, 多个单词用连字符(-)连接. 只能出现英文字母、数字和连字符, 严禁出现中文.
- 该命名规范适用于 html, css, js, swf, php, xml, png, gif, jpg, ico 等前端维护的所有文件类型和相关目录.
- js 和 css 压缩文件, 统一以 -min 结尾, 比如源码文件为 kissy.js, 压缩后为 kissy-min.js .压缩之前的文件使用 –src 结尾。
- 调整自己的编辑器tab制表符一率采用4个空格
前端工程文件组织
注：
- 在resourse/img/中新增一个test文件夹，目的是上传自己的测试图片、占位图片，请勿将网站正式的文件放于此文件夹内，因为此文件夹的内容随时有可能呗任何人删除
- 前端的亲们在写完css文件准备上传时，注意检查一下css文件需要的的图片是否存在，是否存在多余的图片，尽量删除。
文件编码约定
所有文件一律采用utf-8编码
id 和 class 命名约定
- id 和 class 的命名总规则为： 内容优先,表现为辅. 首先根据内容来命名, 比如 main-nav. 如果根据内容找不到合适的命名, 可以再结合表现来定, 比如 skin-blue, present-tab, col-main.
- class 名称一律小写, 多个单词用连字符连接, 比如 recommend-presents.
- class 名称中只能出现小写的 26 个英文字母、数字和连字符(-), 任何其它字符都严禁出现.
- id的命名采用驼峰命名法，首字母小写，如：mainNav
- 仅在 JavaScript 代码中当作 hook 用的 id 或 class, 命名规则为 J_UpperCamelCase``(请注意, ``J_ 后的首字母也大写！), 其中字母 J 代表 JavaScript, 也是钩子(hook)的象形. 注意：如果在 JavaScript 和 CSS 中都需要用到, 则不用遵守本约定
- id 和 class 尽量用英文单词命名 . 确实找不到合适的单词时, 可以考虑使用产品的中文拼音, 比如 wangwang, dating. 对于中国以及淘宝特色词汇, 也可以使用拼音, 比如 xiaobao, daigou. 除了产品名称和特色词汇, 其它任何情况下都严禁使用拼音.
- 在不影响语义的情况下, id 和 class 名称中可以适当采用英文单词缩写, 比如 col, nav, hd, bd, ft 等, 但切忌自造缩写.（常用缩写总结在css规范部分）
- id 和 class 名称中的第一个词必须是单词全拼或语义非常清晰的单词缩写, 比如 present, col.
- 在自动化测试脚本中当作 hook 用的 class, 命名规则为 T_UpperCamelCase, 其中字母 T 代表 Test.
HTML规范
约定
- 所有页面元素的z-index属性值控制在1000以下，将1000-2000留给组件级调用，2000以上用于解决特殊情况下的适应问题；
- 所有的标签及属性名采用小写，DOCTYPE除外；
- 保证标签语义化；
- 分离思想，所有的样式除特殊情况，css样式不能内联写在style属性中；
- table中使用caption,thead,tbody,tfoot标签时若是使用则建议全部使用
- 如非项目需要，不使用html5特有的标签，如canvas。
DOCTYPE
页面文档类型统一使用HTML5 DOCTYPE. 代码如下：
<!doctype html>
另外一种DOCTYPE
采用过渡型 - 相对较为宽松
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
Namespace
<html xmlns="http://www.w3.org/1999/xhtml">
编码
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
编码
声明方法遵循HTML5的规范.
<meta charset="utf-8" >
注释
<!--{nav start}-->
<!--{nav end}-->
元素
推荐使用的元素
- 结构元素：blockquote, body, br, div, h1 - h6, head, hr, html, p
- 头部元素：base, link, meta, script, style, title
- 列表元素：ul, ol, li, dl, dt, dd
- 文本格式元素：a, abbr, acronym, address, bdo, cite, code, del, dfn, em, ins, kbd, noscript, pre, q, samp, small, span, strong, sub, sup, var
- 表单元素：button, fieldset, legend, form, input, label, optgroup, option, select, textarea
- 多媒体元素：area, img, map, object, param
- 表格元素：caption, col, colgroup, table, tbody, td, tfoot, th, thead, tr
- 窗体元素：iframe
不推荐使用的元素
- 结构元素：无
- 头部元素：无
- 列表元素：dir, menu
- 文本格式元素：b, basefont, big, blink, center, comment, font, i, marquee, nobr, plaintext, ruby, s, strike, u, wbr, xmp
- 表单元素：isindex
- 多媒体元素：applet, bgsound, embed, noembed
- 表格元素：无
- 窗体元素：frame, frameset, noframes
转世重生的元素
- s - 表示 sprite, 可以用 <s></s<> 来做 icon 的占位元素
- b - 表示 border, 可以用来作为圆角的占位元素
- i - 预留，尚未想到合理的复活理由（可以考虑作为单个图标的展位符，表示icon）
CSS规范
基本规范
- 模块命名要注意带上模块名，下面尽可能的简写，页面级（app应用级）命名应该尽量简洁
- 尽可能地使用css-sprite
- 尽量通过class属性定义样式,将id留给hook
- 尽量不要在css中使用expression
- 组件开发中，可以先不考虑性能，尽量使用选择符组以方便html调用,如 .table-ctrl tbody tr td.selected{}
- font中的字体用英文或unicode代替,如黑体可写成SimHei：font:12px/1.5 SimHei ,tahoma,arial,\5b8b\4f53,sans-serif;
- 写css属性时，‘：’后面加一个空格增加可读性
引用
统一以link形式引入，不推荐内嵌形式引入css, 不推荐<style></style>标签出现在body中。不推荐内联CSS。如有特别需要(短期推广，特定情况的页面/404错误页面)，请尽量放在head标签内
<style type="text/css" media="style/x.css"></style>
常规引入css文件
<link rel="stylesheet" type="text/css" href="style/x.css"></link>
常用css属性顺序建议
- 显示属性(display, list-style, position, float, clear)
- 盒模型(width, height, margin, padding, border, background)
- 文本属性(color, font, text-decoration, text-align, vertical-align, white-space, other text, content)
注释风格
头注释
/*---------------------------------------------------------------------------------------------
@Filename: main.css
@Description: 全局css定义
@Version: 1.0.0(2009-12-28)YYYY-MM-DD
@author: simon-shen
==STRUCTURE:=========================================
$__header
$__menu
==NOTES:=============================================
2011-11-2:
初始生成。
2011-11-3:
更改文档结构和注释
--------------------------------------------------------------------------------------------*/
区块
/*__header
--------------------------------------------------------------------------------------------*/
/*__menu
--------------------------------------------------------------------------------------------*/
编码风格
Css组合嵌套的时候采用换行以提高可读性
h2 { color: red; }
.w3cbbs { color: red; }
.w3cbbs_52css { color: red; }
则可以这样写
h2,
.w3cbbs,
.w3cbbs_52css { color: red; }
如果对css文件不适用最小化处理，发布时采用single-line处理，如：
.form-normal .field{position:relative;border-bottom:1px solid #ddd;overflow:hidden;}
常用css命名参考
| 导航 | nav | 页头 | header |
|---|---|---|---|
| 主导航 | mainnav | 页面主体 | main |
| 顶导航 | topnav | 内容 | content |
| 子导航 | subnav | 页脚 | footer |
| 菜单 | menu | 版权 | copyright |
| 子菜单 | submenu | 登陆 | login |
| 标志 | logo | 侧栏 | sidebar |
| 广告 | banner | 搜索 | search |
| 滚动 | scroll | 标签页 | tab |
| 小技巧 | tips | 合作伙伴 | partner |
| 加入 | joinus | 标题 | title |
| 注册 | regsiter | 指南 | gUIld |
| 新闻 | news | 下载 | download |
| 按钮 | button | 状态 | status |
| 服务 | service | 投票 | vote |
| 注释 | note | 友情链接 | friendlink |
Javascript规范
命名参考
原则： * 尽量避免潜在冲突; * 精简短小, 见名知意
- 全局变量以$开头，如$user，相当于：window.$user
- 常量全部大写，单词以下划线分隔，如STATIC_ROOT
- 变量采用驮峰式写法，如userIcon，UserRelation
- 类名首字母大写，如Object = function(){}
- 普通变量、命名空间，首字母小写
- 局部变量可缩写，命名空间，类名尽量不缩写
- 条件表达式、正则表式式，如果很复杂，给其命名
- 枚举量, 同常量;
- 私有变量, 属性和方法, 名字以下划线开头,如_init(),_param;
- 保护变量, 属性和方法, 名字同普通变量名;
- 方法和函数的可选参数, 名字以 opt_ 开头, 使用 @param 标记说明;(试行)
- 使用 @param 标记说明;
- 外部代码和内部代码使用不同的命名空间;
- 重命名那些名字很长的变量, 不要在全局范围内创建别名, 而仅在函数块作用域中使用;
- 文件名应全部使用小写字符, 且不包含除 - 和 _ 外的标点符号;
- 临时的重复变量建议以 i, j, k, ..., 命名;
原则
- 任何插件的开发都要写入version参数，至少要在注释中注明版本信息及修改内容.
- 声明变量时, 必须加上 var 关键字.
- 尽量减少全局变量的使用.
- 语句总是以分号结尾.
- 不要在块内声明函数.
- 标准特性优于非标准特性(如果类库有提供, 优先使用类库中的函数).
- 不要封装基本类型.
- 只在解析序列化串时使用 eval() .
- 禁止使用 with .
- 减少使用 continue 和 break .
- 仅在函数内使用 this .
- 使用 Array/Object 直接量, 避免使用 Array/Object 构造器.
- 禁止修改内置对象的原型.
- 坚决不在主页面中嵌入逻辑脚本，
- 坚决不在ajax载入的HTML片段里面嵌入脚本，载入后要执行代码，可以写在回调里面
编码风格
引用
<script type="text/javascript" src=”xx”></script>
页面内的脚本只作初始化及参数配置使用
<script type="text/javascript">
$(function(){
$.nav.init({
id : 1,
name : 'simon'
})
})
</script>
注：具体使不使用init()函数视具体情况及个人编程习惯而定，但是个人建议使用，方便读代码的人找到入口
行与缩进
语句行
- 尽可能不要让每行超过 120 个字符;
- 语句必须以分号作为结束符, 不要忽略分号;
空格
- 数值操作符(如, +/-/*/% 等)两边留空;
- 赋值操作符/等价判断符两边留一空格;
- for 循环条件中, 分号后留一空格;
- 变量声明语句, 数组值, 对象值及函数参数值中的逗号后留一空格;
- 空行不要有空格;
- 行尾不要有空格;
- 逗号和冒号后一定要跟空格;
- 点号前后不要出现空格;
- 空对象和数组不需要填入空格;
- 函数名末尾和左括号之间不要出现空格;
空行
- 逻辑上独立的代码块使用空行分隔;
- 文件末尾留 1~2 个空行;
- 不要吝啬空行. 尽量使用空行将逻辑相关的代码块分割开, 以提高程序的可读性.
变量声明
- 多个变量声明时, 适当换行表示;
- 参照 var 关键字, 缩进一层次;
函数参数
- 函数参数写在同一行上;
- 传递匿名函数时, 函数体应从调用该函数的左边开始缩进;
- 数组和对象初始化时:如果初始值不是很长, 尽量保持写在单行上;
- 初始值占用多行时, 缩进一层次;
- 对象中, 比较长的变量/数值, 不要以冒号对齐;
- 二元/三元操作符:操作符始终跟随前行;
- 实在需要缩进时, 按照上述缩进风格;
- 表达式中的缩进同变量声明时;
括号
- 原则: 不要滥用括号, 必要时一定要使用.
- if/else/while/for 条件表达式必须有小括号;
- 语句块必须有大括号;
- 一元操作符(如 delete, typeof, void)或在某些关键词(如 return, throw, case, new) 之后, 不要使用括号;
语句行
- 变量如有较广的作用域, 使用全局变量; 如果是在类中, 可以设计成为一个类的成员;
- 函数体中, 多个局部变量集中在一起声明, 避免分散;
- 适当延迟变量的初始化;
字符串
- JS 代码中, 单行字符串使用单引号;
- JS 代码中, 多行字符串使用 + 拼接形式, 不要使用 \ 拼接;
- HTML 中 Element 属性, 使用双引号;
标准文档实例
通用模板库
准备中……
资源列表
小技巧总结
准备中……
备注
- 此文档只作前端开发参考用，本意只为规范前端开发人员的编码规范，使各成员之间的代码更易理解，并不想打压各位前端的创造灵感；
- 此文档还有待调整，如果有不足的地方可以私信发给我！
214
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
