Frontend Basic Rule

阅读更多

通用约定

文件与目录命名

• 一律小写, 必须是英文单词或产品名称的拼音, 多个单词用连字符(-)连接. 只能出现英文字母、数字和连字符, 严禁出现中文.
• 该命名规范适用于 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

采用过渡型 - 相对较为宽松

Namespace

编码

编码

声明方法遵循HTML5的规范.

注释

元素

推荐使用的元素

1. 结构元素：blockquote, body, br, div, h1 - h6, head, hr, html, p
2. 头部元素：base, link, meta, script, style, title
3. 列表元素：ul, ol, li, dl, dt, dd
4. 文本格式元素：a, abbr, acronym, address, bdo, cite, code, del, dfn, em, ins, kbd, noscript, pre, q, samp, small, span, strong, sub, sup, var
5. 表单元素：button, fieldset, legend, form, input, label, optgroup, option, select, textarea
6. 多媒体元素：area, img, map, object, param
7. 表格元素：caption, col, colgroup, table, tbody, td, tfoot, th, thead, tr
8. 窗体元素：iframe

不推荐使用的元素

1. 结构元素：无
2. 头部元素：无
3. 列表元素：dir, menu
4. 文本格式元素：b, basefont, big, blink, center, comment, font, i, marquee, nobr, plaintext, ruby, s, strike, u, wbr, xmp
5. 表单元素：isindex
6. 多媒体元素：applet, bgsound, embed, noembed
7. 表格元素：无
8. 窗体元素：frame, frameset, noframes

转世重生的元素

1. s - 表示 sprite, 可以用 来做 icon 的占位元素
2. b - 表示 border, 可以用来作为圆角的占位元素
3. 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, 不推荐标签出现在body中。不推荐内联CSS。如有特别需要(短期推广，特定情况的页面/404错误页面)，请尽量放在head标签内

常规引入css文件

常用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片段里面嵌入脚本，载入后要执行代码，可以写在回调里面

编码风格

引用

页面内的脚本只作初始化及参数配置使用

注：具体使不使用init()函数视具体情况及个人编程习惯而定，但是个人建议使用，方便读代码的人找到入口

行与缩进

语句行

• 尽可能不要让每行超过 120 个字符;
• 语句必须以分号作为结束符, 不要忽略分号;

空格

• 数值操作符(如, +/-/*/% 等)两边留空;
• 赋值操作符/等价判断符两边留一空格;
• for 循环条件中, 分号后留一空格;
• 变量声明语句, 数组值, 对象值及函数参数值中的逗号后留一空格;
• 空行不要有空格;
• 行尾不要有空格;
• 逗号和冒号后一定要跟空格;
• 点号前后不要出现空格;
• 空对象和数组不需要填入空格;
• 函数名末尾和左括号之间不要出现空格;

空行

• 逻辑上独立的代码块使用空行分隔;
• 文件末尾留 1~2 个空行;
• 不要吝啬空行. 尽量使用空行将逻辑相关的代码块分割开, 以提高程序的可读性.

变量声明

• 多个变量声明时, 适当换行表示;
• 参照 var 关键字, 缩进一层次;

函数参数

• 函数参数写在同一行上;
• 传递匿名函数时, 函数体应从调用该函数的左边开始缩进;
• 数组和对象初始化时:如果初始值不是很长, 尽量保持写在单行上;
• 初始值占用多行时, 缩进一层次;
• 对象中, 比较长的变量/数值, 不要以冒号对齐;
• 二元/三元操作符:操作符始终跟随前行;
• 实在需要缩进时, 按照上述缩进风格;
• 表达式中的缩进同变量声明时;

括号

• 原则: 不要滥用括号, 必要时一定要使用.
• if/else/while/for 条件表达式必须有小括号;
• 语句块必须有大括号;
• 一元操作符(如 delete, typeof, void)或在某些关键词(如 return, throw, case, new) 之后, 不要使用括号;

语句行

• 变量如有较广的作用域, 使用全局变量; 如果是在类中, 可以设计成为一个类的成员;
• 函数体中, 多个局部变量集中在一起声明, 避免分散;
• 适当延迟变量的初始化;

字符串

• JS 代码中, 单行字符串使用单引号;
• JS 代码中, 多行字符串使用 + 拼接形式, 不要使用 \ 拼接;
• HTML 中 Element 属性, 使用双引号;

标准文档实例

• 标准html文档
• 标准css文档
• js参考文档

通用模板库

准备中……

资源列表

• 字体编码查询