这个是平时在和前端打交道时发现一些小伙伴代码不够规范,遂有兴趣参考了国内外有公开规范的互联网公司的内容综合来总结出一个适合自己的.
中间有部分示例是一些经典问题的较优的解决方案,值得学习
正文如下
通用篇
多 IDE or 编辑器平台代码格式统一
Tab缩进 使用 4个Soft-Space 保证全平台代码表现一致性
Eclipse设置在 Window->Preferences->general->editors->text editors display tab width:4 勾选 Insert Spaces for tabs Show Print Margin Print Margin column:80 其他编辑器 or IDE 类似设置。
不要混用tab和space；
不要在一处使用多个tab或space；
换行符统一用'LF'。
命名规则
项目命名
项目名全部采用小写方式， 以中划线分隔。 比如： my-project-name。
目录名
目录名参照上一条规则,有复数结构时，要采用复数命名法，比如说： scripts, styles, images, data-models。
HTML文件名
多个单词组成时，采用中划线连接方式，比如说: error-report.html。
CSS，SCSS 样式文件命名
多个单词组成时，采用中划线连接方式，比如说：retina-sprites.scss。
HTML 篇
HTML 基础配置
- 文件应以
<!DOCTYPE ......>首行顶格开始，推荐使用<!DOCTYPE html>即HTML5文件头。 - 必须申明文档的编码charset，且与文件本身编码保持一致，推荐使用UTF-8编码
<meta charset="utf-8"/>。 - 根据页面内容和需求填写适当的
keywords和description。 - 页面
title是极为重要的不可缺少的一项。
** 示例代码 **
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8"/>
<title>Welcome to SZUNICOM</title>
<meta http-equiv="X-UA-Compatible" content="IE=Edge"/>
<meta name="keywords" content=""/>
<meta name="description" content=""/>
<meta name="viewport" content="width=device-width"/>
<link rel="stylesheet" href="css/style.css"/>
<link rel="shortcut icon" href="img/favicon.ico"/>
<link rel="apple-touch-icon" href="img/touchicon.png"/>
</head>
<body>
</body>
</html>
keywords、 description 主要是针对网络爬虫有利于页面的SEO，提高权重，主要针对外部开放系统，内部系统可以忽略。
语义化使用 HTML 标签
HTML 标签属性应该按照特定的顺序出现以保证易读性
- id
- class
- name
- data-*
- src, for, type, href
- title, alt
- aria-*, role
注释标准格式写法
代码说明的注释方法
解决无法定位所写注释对应的代码从哪里开始，又到哪里结束的问题。
-
开始注释：
<!-- 注释说明 -->（文案两头空格）。 -
结束注释：
<!-- /注释说明 -->（文案前加“/”符号，类似标签的闭合）。 -
允许只有开始注释。
** 示例代码 **
<!-- 头部 -->
<div class="g-hd">
<!-- LOGO -->
<h1 class="m-logo"><a href="#">LOGO</a></h1>
<!-- /LOGO -->
<!-- 导航 -->
<ul class="m-nav">
<li><a href="#">NAV1</a></li>
<li><a href="#">NAV2</a></li>
<!-- 更多导航项 -->
</ul>
<!-- /导航 -->
</div>
<!-- /头部 -->
代码本身的注释方法
- 单行代码的注释也保持同行，两端空格；
- 多行代码的注释起始和结尾都另起一行并左缩进对齐。
** 示例代码 **
<!-- <h1 class="m-logo"><a href="#">LOGO</a></h1> -->
<!--
<ul class="m-nav">
<li><a href="#">NAV1</a></li>
<li><a href="#">NAV2</a></li>
</ul>
-->
CSS篇
CSS书写规范
-
样式书写顺序
只遵循横向顺序即可，先显示定位布局类属性，后盒模型等自身属性，最后是文本类及修饰类属性。
| 显示属性 | 自身属性 | 文本属性和其他修饰 |
|---|---|---|
| display | width | font |
| visibility | height | text-align |
| position | margin | text-decoration |
| float | padding | vertical-align |
| clear | border | white-space |
| list-style | overflow | color |
| top | min-width | background |
在各种编辑器中使用css-comb插件可以实现自动排序 sublime、atom都支持
-
最后一个值也以分号结尾
通常在大括号结束前的值可以省略分号，但是这样做会对修改、添加和维护工作带来不必要的失误和麻烦。
-
省略值为0时的单位
为节省不必要的字节同时也使阅读方便，我们将0px、0em、0%等值缩写为0。
.m-box {
margin:0 10px;
background-position:50% 0;
}
-
私有在前，标准在后
先写带有浏览器私有标志的，后写W3C标准的。
.m-box {
-webkit-box-shadow:0 0 0 #000;
-moz-box-shadow:0 0 0 #000;
box-shadow:0 0 0 #000;
}
- 不要在颜色值 rgb() rgba() hsl() hsla()和 rect()中增加空格，并且不要带有取值前面不必要的 0 (比如，使用 .5 替代 0.5)。
CLASS 命名规则
使用单个字母加"-"为前缀
- 布局（grid）（.g-）；模块（module）（.m-）；元件（unit）（.u-）；功能（function）（.f-）；皮肤（skin）（.s-）；状态（.z-）。
| 功能 | 说明 | 英文名 | css缩写 |
|---|---|---|---|
| 布局 | 将页面分割为几个大块，通常有头部、主体、主栏、侧栏、尾部等！ | grid | .g- |
| 模块 | 一个语义化的可以重复使用的较大的整体！比如导航、登录、注册、各种列表、评论、搜索等 | module | .m- |
| 原件 | 不可再分的较为小巧的个体，通常被重复用于各种模块中！比如按钮、输入框、loading、图标等 | unit | .u- |
| 功能 | 一些常用样式的使用，我们将这些使用率较高的样式剥离出来，按需使用，通常这些选择器具有固定样式表现，比如清除浮动等！不可滥用！ | function | .f- |
| 皮肤 | 你需要把皮肤型的样式抽离出来，通常为文字色、背景色（图）、边框色等，非换肤型网站通常只提取文字色！非换肤型网站不可滥用此类！ | skin | .s- |
| 状态 | 状态类样式加入前缀，统一标识，方便识别，她只能组合使用或作为后代出现（.u-ipt.z-dis{}，.m-list li.z-sel{}）(因重名用拼音替代) | status | .z- |
| 获取节点 | 专用于JS获取节点，请勿使用.j-定义样式 | - | .j- |
注：在你样式中的选择器总是要以上面前五类开头，然后在里面使用后代选择器。如果这五类不能满足你的需求，你可以另外定义一个或多个大类，但必须符合单个字母+"-"为前缀的命名规则，即 .x- 的格式。
当前的工作环境中主要使用布局、模块、原件、功能、状态、节点选取前缀，皮肤作为后期有主题类界面开发预留。
示例代码
<style type="text/css">
/* 图片居中溢出隐藏 */
.m-demo{
position:relative;
width:300px;
height:300px;
overflow:hidden;
border:1px solid #ddd;
}
.m-demo p{
position:absolute;
top:50%;left:50%;
margin:0;
padding:0;
}
.m-demo img{
position:absolute;
top:-50%;
left:-50%;
display:block;
}
.m-demo img.hidden{
visibility:hidden;
position:static;
}
</style>
<div class="m-demo">
<p>
<img src="http://nec.netease.com/img/s/1.jpg" class="hidden"/>
<img src="http://nec.netease.com/img/s/1.jpg" alt=""/>
</p>
</div>
<div class="m-demo">
<p>
<img src="http://nec.netease.com/img/m/1.jpg" class="hidden"/>
<img src="http://nec.netease.com/img/m/1.jpg" alt=""/>
</p>
</div>
<div class="m-demo">
<p>
<img src="http://nec.netease.com/img/l/1.jpg" class="hidden"/>
<img src="http://nec.netease.com/img/l/1.jpg" alt=""/>
</p>
</div>
一些常用模块class命名参考
| 模块 | class命名 |
|---|---|
| 头 | header |
| 内容 | content/container |
| 尾 | footer |
| 导航 | nav |
| 侧栏 | sidebar |
| 栏目 | column |
| 页面外围控制整体佈局宽度 | wrapper |
| 左右中 | left right center |
| 登录条 | loginbar |
| 标志 | logo |
| 广告 | banner |
| 页面主体 | main |
| 热点 | hot |
| 新闻 | news |
| 下载 | download |
| 子导航 | subnav |
| 菜单 | menu |
| 子菜单 | submenu |
| 搜索 | search |
| 友情链接 | friendlink |
| 页脚 | footer |
| 版权 | copyright |
| 滚动 | scroll |
| 内容 | content |
| 标签 | tags |
| 文章列表 | list |
| 提示信息 | msg |
| 小技巧 | tips |
| 栏目标题 | title |
| 加入 | joinus |
| 指南 | guide |
| 服务 | service |
| 注册 | regsiter |
| 状态 | status |
| 投票 | vote |
| 合作伙伴 | partner |
备注标准格式写法
- 对选择器的注释统一写在被注释对象的上一行，对属性及值的注释写于分号后。
- 注释内容两端需空格，已确保即使在编码错误的情况下也可以正确解析样式。
- 在必要的情况下，可以使用块状注释，块状注释保持统一的缩进对齐。
示例代码
/* 块状注释文字
* 块状注释文字
* 块状注释文字
*/
.m-list {
width:500px;
}
.m-list li {
height:20px;
line-height:20px;/* 这里是对line-height的一个注释 */
overflow:hidden;
}
.m-list li a {
color:#333;
}
/* 单行注释文字 */
.m-list li em {
color:#666;
}
让CSS做更多的事，减轻JS开发量。
- 用CSS控制交互或视觉的变化，JS只需要更改className。
- 利用CSS一次性更改多个节点样式，避免多次渲染，提高渲染效率。
- 如果你的产品允许不兼容低版本浏览器，那么动画实现可以交给CSS。
JavaScript篇
部分代码书写约束
空行
- 方法之间加
- 单行或多行注释前加
- 逻辑块之间加空行增加可读性
- 变量命名
- 文件最后保留一个空行
标准变量采用驼峰标识
- 使用的ID的地方一定全大写
- 使用的URL的地方一定全大写, 如
reportURL - 涉及Android的，一律大写第一个字母
- 涉及iOS的，一律小写第一个，大写后两个字母
- 常量采用大写字母，下划线连接的方式
- 构造函数，大写第一个字母
示例代码
var thisIsMyName; //注释说明
var goodID; //注释说明
var AndroidVersion; //注释说明
var iOSVersion; //注释说明
var MAX_COUNT = 10; //注释说明
/** 注释内容与星标前保留一个空格 */
function Person (name) {
this.name = name;
}
使用帕斯卡式命名构造函数或类
示例代码
// bad
function user(options) {
this.name = options.name;
}
var bad = new user({
name: 'nope'
});
/** 骆驼命名法是首字母小写，而帕斯卡命名法是首字母大写。*/
**示例代码**
// good
function User(options) {
this.name = options.name;
}
var good = new User({
name: 'yup'
});
字符常量
- 一般情况下统一使用
' '单引号
数组、对象
- 对象属性名不需要加引号；
- 对象以缩进的形式书写，不要写在一行；
- 数组、对象最后不要有逗号。
示例代码
// not good
var a = {
'b': 1
};
var a = {b: 1};
var a = {
b: 1,
c: 2,
};
// good
var a = {
b: 1,
c: 2
};
事件命名
-
添加节点事件的命名规则 on + 名词 + 动作 符合驼峰规则
如页面上有一个
editBtn的按钮，要给这个按钮添加点击事件时，可以命名成onEditBtnClick,如果是鼠标悬停，onEditBtnMouseover等这样的一种命名规则。 -
除了事件的命名外，其他的所有回调函数都以cb开头。
如item里对模块的回调，cache对外面的回调等都以cb开头 + 名词 + 动词。
不要使用下划线前/后缀
JavaScript 并没有私有属性或私有方法的概念。虽然使用下划线是表示「私有」的一种共识，但实际上这些属性是完全公开的，它本身就是你公共接口的一部分。这种习惯或许会导致开发者错误的认为改动它不会造成破坏或者不需要去测试。长话短说：如果你想要某处为「私有」，它必须不能是显式提出的。
示例代码
// bad
this.__firstName__ = 'Panda';
this.firstName_ = 'Panda';
this._firstName = 'Panda';
// good
this.firstName = 'Panda';
括号
下列关键字后必须有大括号（即使代码块的内容只有一行）：if, else, for, while, do, switch, try, catch, finally, with。
示例代码
// not good
if (condition)
doSomething();
// good
if (condition) {
doSomething();
}
函数格式
-
无论是函数声明还是函数表达式，'('前不要空格，但'{'前一定要有空格；
-
函数调用括号前不需要空格；
-
立即执行函数外必须包一层括号；
-
不要给inline function命名；
-
参数之间用
空格逗号分隔，注意逗号后有一个空格。
示例代码
// no space before '(', but one space before'{'
var doSomething = function(item) {
// do something
};
function doSomething(item) {
// do something
}
// not good
doSomething (item);
// good
doSomething(item);
// requires parentheses around immediately invoked function expressions
(function() {
return 1;
})();
// not good
[1, 2].forEach(function x() {
...
});
// good
[1, 2].forEach(function() {
...
});
// not good
var a = [1, 2, function a() {
...
}];
// good
var a = [1, 2, function() {
...
}];
// use ', ' between function parameters
var doSomething = function(a, b, c) {
// do something
};
函数块中一些需要注意的问题
不要保存 this 的引用。使用 Function#bind
示例代码
// bad
function () {
var self = this;
return function () {
console.log(self);
};
}
// bad
function () {
var that = this;
return function () {
console.log(that);
};
}
// bad
function () {
var _this = this;
return function () {
console.log(_this);
};
}
// good
function () {
return function () {
console.log(this);
}.bind(this);
}
这个做法比较激进，和国内的很多互联网公司的代码规范不太一样。
null的使用
适用场景：
- 初始化一个将来可能被赋值为对象的变量
- 与已经初始化的变量做比较
- 作为一个参数为对象的函数的调用传参
- 作为一个返回对象的函数的返回值
不适用场景：
- 不要用null来判断函数调用时有无传参
- 不要与未初始化的变量做比较
示例代码
// not good
function test(a, b) {
if (b === null) {
// not mean b is not supply
...
}
}
var a;
if (a === null) {
...
}
// good
var a = null;
if (a === null) {
...
}
条件表达式例如 if 语句通过抽象方法 To Boolean 强制计算它们的表达式并且总是遵守如下规则：
- 对象 被计算为 true
- Undefined 被计算为 false
- Null 被计算为 false
- 布尔值 被计算为 布尔的值
- 数字 如果是 +0、-0 或 NaN 被计算为 false，否则为 true
- 字符串 如果是空字符串 '' 被计算为 false，否则为 true
示例代码
if ([0]) {
// true
// 一个数组就是一个对象，对象被计算为 true
}
// bad
if (name !== '') {
// ...stuff...
}
// good
if (name) {
// ...stuff...
}
// bad
if (collection.length > 0) {
// ...stuff...
}
// good
if (collection.length) {
// ...stuff...
}
减少 == != 的使用， 优先用严格比较条件 === !==;
其他细节问题
如果你的文件导出一个类，你的文件名应该与类名完全相同
示例代码
// file contents
class CheckBox {
// ...
}
module.exports = CheckBox;
// in some other file
// bad
var CheckBox = require('./checkBox');
// bad
var CheckBox = require('./check_box');
// good
var CheckBox = require('./CheckBox');
268
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
