一、前端编辑器
vscode 对angular、typescript有着非常友好的支持,轻便快捷,代码统一,一键格式化。
1.编辑器 NO1:Visual Studio Code
- vscode格式化插件:Beautify css/sass/scss/less、px to rem。其余的用自带的格式化工具。
二、前端文件夹结构及命名规范
- 项目命名,全部采用小写方式, 以下划线分隔。例:
my_project_name
; - 目录命名,参照项目命名规则;有复数结构时,要采用复数命名法。。例:
scripts, styles, images, data_models
; - HTML文件命名,参照项目命名规则。例:
error_report.html
; - CSS, SCSS文件命名,参照项目命名规则。例:
retina_sprites.scss
; - JS文件命名,参照项目命名规则。例:
account_model.js
;
某些框架自身的文件命名风格可能特殊,比如sails是用大驼峰,angular是-comporent.ts等等,此时以框架命名风格为准。
参考《Angular官方命名风格指南》、《Vue官方命名风格指南》
我们自己的标准的前端命名规范基本模板,前端+nodejs结构:angular4戳这里,vue戳这里。
三、HTML
语法
- 全部使用双引号,不要使用单引号;
- 属性名全小写,用中划线做分隔符;
- 大的块之间要用
,而不是
;- 充分利用html自带语意标签,如
、
;
注释
涉及到大的复杂html片段要添加注释利于阅读。
- 大的模块html片段要用注释开始和注释结束两个包起来;
- 小的功能性html片段只需使用注释开始;
属性顺序
属性应该按照特定的顺序出现以保证易读性;class是为高可复用组件设计的,所以应处在第一位;id除非是锚点,否则不要用。第三方框架框架自带的指令放在最后面。
class
name
src, for, type, href, value , max-length, max, min, pattern
placeholder, title, alt
required, readonly, disabled
[(ngModel)],ngclass
Example link
四、CSS/SCSS
语法
- css命名全部用中滑线做分隔符;
- 属性名全小写,用中划线做分隔符;
- 命名方式采用功能-样式的方式,如红色按钮就是
.btn-red
空格
不需要空格 需要空格 属性名后 属性值前 多个规则的分隔符','前 选择器'>', '+', '~'前后 !important '!'后 !important '!'前 属性值中'('后和')'前 @else 前后、属性值中的','后 行末不要有多余的空格 注释'/'后和'/'前 /* not good */ .element { color :red! important; background-color: rgba(0,0,0,.5); } /* good */ .element { color: red !important; background-color: rgba(0, 0, 0, .5); } /* not good */ .element , .dialog{ ... } /* good */ .element, .dialog { } /* not good */ .element>.dialog{ ... } /* good */ .element > .dialog{ ... } /* not good */ .element{ ... } /* good */ .element { ... } /* not good */ @if{ ... }@else{ ... } /* good */ @if { ... } @else { ... }
空行
以下几种情况需要空行:
- 文件最后保留一个空行
- '}'后最好跟一个空行,包括scss中嵌套的规则
- 属性之间需要适当的空行
/* not good */ .element { ... } .dialog { color: red; &:after { ... } } /* good */ .element { ... } .dialog { color: red; &:after { ... } }
换行
以下几种情况不需要换行:
- '{'前
以下几种情况需要换行:
- '{'后和'}'前
- 每个属性独占一行
- 多个规则的分隔符','后
/* not good */ .element {color: red; background-color: black;} /* good */ .element { color: red; background-color: black; } /* not good */ .element, .dialog { ... } /* good */ .element, .dialog { ... }
注释
- 注释统一用'/* */'(scss中也不要用'//'
- 缩进与下一行代码保持一致;
- 可位于一个代码行的末尾,与代码间隔一个空格。
/* Modal header */ .modal-header { ... } /* * Modal header */ .modal-header { ... } .modal-header { /* 50px */ width: 50px; color: red; /* color red */ }
引号
- 最外层统一使用双引号;
- url的内容要用引号;
- 属性选择器中的属性值需要引号。
.element:after { content: ""; background-image: url("logo.png"); } li[data-type="single"] { ... }
命名
- 类名使用小写字母,以中划线分隔
- id采用驼峰式命名
- scss中的变量、函数、混合、placeholder采用驼峰式命名
/* class */ .element-content { ... } /* id */ #myDialog { ... } /* 变量 */ $colorBlack: #000; /* 函数 */ @function pxToRem($px) { ... } /* 混合 */ @mixin centerBlock { ... } /* placeholder */ %myDialog { ... }
属性声明顺序
- 相关的属性声明按右边的顺序做分组处理,组之间需要有一个空行。
.declaration-order { display: block; float: right; position: absolute; top: 0; right: 0; bottom: 0; left: 0; z-index: 100; border: 1px solid #e5e5e5; border-radius: 3px; width: 100px; height: 100px; font: normal 13px "Helvetica Neue", sans-serif; line-height: 1.5; text-align: center; color: #333; background-color: #f5f5f5; opacity: 1; }
颜色
- 颜色16进制用小写字母;
- 颜色16进制尽量用简写;
/* not good */ .element { color: #ABCDEF; background-color: #001122; } /* good */ .element { color: #abcdef; background-color: #012; }
属性简写
属性简写需要你非常清楚属性值的正确顺序,而且在大多数情况下并不需要设置属性简写中包含的所有值,所以建议尽量分开声明会更加清晰;
- margin 和 padding 相反,需要使用简写;
常见的属性简写包括:
font
background
transition
animation
/* not good */ .element { transition: opacity 1s linear 2s; } /* good */ .element { transition-delay: 2s; transition-timing-function: linear; transition-duration: 1s; transition-property: opacity; }
媒体查询
尽量将媒体查询的规则靠近与他们相关的规则,不要将他们一起放到一个独立的样式文件中,或者丢在文档的最底部,这样做只会让大家以后更容易忘记他们。除了rem这样的全局范围的例外。
.element { ... } .element-avatar{ ... } @media (min-width: 480px) { .element { ... } .element-avatar { ... } }
SCSS相关
- 提交的代码中不要有 @debug;
- 声明顺序:
@extend 不包含 @content 的 @include 包含 @content 的 @include 自身属性 嵌套规则
- @import 引入的文件不需要开头的'_'和结尾的'.scss';
- 嵌套最多不能超过5层;
- @extend 中使用placeholder选择器;
- 去掉不必要的父级引用符号'&'。
/* not good */ @import "_dialog.scss"; /* good */ @import "dialog"; /* not good */ .fatal { @extend .error; } /* good */ .fatal { @extend %error; } /* not good */ .element { & > .dialog { ... } } /* good */ .element { > .dialog { ... } }
其他
- 不允许有空的规则;
- 元素选择器用小写字母;
- 去掉小数点前面的0;
- 去掉数字中不必要的小数点和末尾的0;
- 属性值'0'后面不要加单位;
- 同个属性不同前缀的写法需要在垂直方向保持对齐。
- 无前缀的标准属性应该写在有前缀的属性后面;
- 不要在同个规则里出现重复的属性,如果重复的属性是连续的则没关系;
- 不要在一个文件里出现两个相同的规则;
- 用
border: 0;
代替border: none;
; - 选择器不要超过4层(在scss中如果超过4层应该考虑用嵌套的方式来写);
- 发布的代码中不要有
@import
; - 尽量少用'*'选择器。
/* not good */ .element { } /* not good */ LI { ... } /* good */ li { ... } /* not good */ .element { color: rgba(0, 0, 0, 0.5); } /* good */ .element { color: rgba(0, 0, 0, .5); } /* not good */ .element { width: 50.0px; } /* good */ .element { width: 50px; } /* not good */ .element { width: 0px; } /* good */ .element { width: 0; } /* not good */ .element { border-radius: 3px; -webkit-border-radius: 3px; -moz-border-radius: 3px; background: linear-gradient(to bottom, #fff 0, #eee 100%); background: -webkit-linear-gradient(top, #fff 0, #eee 100%); background: -moz-linear-gradient(top, #fff 0, #eee 100%); } /* good */ .element { -webkit-border-radius: 3px; -moz-border-radius: 3px; border-radius: 3px; background: -webkit-linear-gradient(top, #fff 0, #eee 100%); background: -moz-linear-gradient(top, #fff 0, #eee 100%); background: linear-gradient(to bottom, #fff 0, #eee 100%); } /* not good */ .element { color: rgb(0, 0, 0); width: 50px; color: rgba(0, 0, 0, .5); } /* good */ .element { color: rgb(0, 0, 0); color: rgba(0, 0, 0, .5); }
五、Javascript
分号
以下几种情况后需加分号:
- 变量声明
- 表达式
- return
- throw
- break
- continue
- do-while
/* var declaration */ var x = 1; /* expression statement */ x++; /* do-while */ do { x++; } while (x < 10);
空格
不需要空格 需要空格 对象的属性名后 二元运算符前后 前缀一元运算符后','前 三元运算符'?:'前后 后缀一元运算符前 代码块'{'前 函数调用括号前 下列关键字前:else, while, catch, finally 无论是函数声明还是函数表达式,'('前不要空格 下列关键字后:if, else, for, while, do, switch, case, try, catch, finally, with, return, typeof 数组的'['后和']'前 单行注释'//'后(若单行注释和代码同行,则'//'前也需要),多行注释'*'后 对象的'{'后和'}'前 对象的属性值前 运算符'('后和')'前 函数的参数之间 // not good var a = { b :1 }; // good var a = { b: 1 }; // not good ++ x; y ++; z = x?1:2; // good ++x; y++; z = x ? 1 : 2; // not good var a = [ 1, 2 ]; // good var a = [1, 2]; // not good var a = ( 1+2 )*3; // good var a = (1 + 2) * 3; // no space before '(', one space before '{', one space between function parameters var doSomething = function(a, b, c) { // do something }; // no space before '(' doSomething(item); // not good for(i=0;i<6;i++){ x++; } // good for (i = 0; i < 6; i++) { x++; }
空行
以下几种情况需要空行:
- 变量声明后(当变量声明在代码块的最后一行时,则无需空行)
- 注释前(当注释在代码块的第一行时,则无需空行)
- 代码块后(在函数调用、数组、对象中则无需空行)
- 文件最后保留一个空行
// need blank line after variable declaration var x = 1; // not need blank line when variable declaration is last expression in the current block if (x >= 1) { var y = x + 1; } var a = 2; // need blank line before line comment a++; function b() { // not need blank line when comment is first line of block return a; } // need blank line after blocks for (var i = 0; i < 2; i++) { if (true) { return false; } continue; } var obj = { foo: function() { return 1; }, bar: function() { return 2; } }; // not need blank line when in argument list, array, object func( 2, function() { a++; }, 3 ); var foo = [ 2, function() { a++; }, 3 ]; var foo = { a: 2, b: function() { a++; }, c: 3 };
换行
换行的地方,行末必须有','或者运算符;
以下几种情况不需要换行:
- 下列关键字后:else, catch, finally
- 代码块'{'前
以下几种情况需要换行:
- 代码块'{'后和'}'前
- 变量赋值后
// not good var a = { b: 1 , c: 2 }; x = y ? 1 : 2; // good var a = { b: 1, c: 2 }; x = y ? 1 : 2; x = y ? 1 : 2; // no need line break with 'else', 'catch', 'finally' if (condition) { ... } else { ... } try { ... } catch (e) { ... } finally { ... } // not good function test() { ... } // good function test() { ... } // not good var a, foo = 7, b, c, bar = 8; // good var a, foo = 7, b, c, bar = 8;
单行注释
- 双斜线后,必须跟一个空格;
- 缩进与下一行代码保持一致;
- 可位于一个代码行的末尾,与代码间隔一个空格。
if (condition) { // if you made it here, then all security checks passed allowed(); } var zhangsan = 'zhangsan'; // one space after code
多行注释
最少三行,
*
后跟一个空格建议在以下情况下使用:
- 难于理解的代码段
- 可能存在错误的代码段
- 浏览器特殊的HACK代码
- 业务逻辑强相关的代码
/* * one space after '*' */ var x = 1;
文档注释
各类标签@param, @method等请参考usejsdoc和JSDoc Guide;
建议在以下情况下使用:
- 所有常量
- 所有函数
- 所有类
/** * @func * @desc 一个带参数的函数 * @param {string} a - 参数a * @param {number} b=1 - 参数b默认值为1 * @param {string} c=1 - 参数c有两种支持的取值1—表示x2—表示xx * @param {object} d - 参数d为一个对象 * @param {string} d.e - 参数d的e属性 * @param {string} d.f - 参数d的f属性 * @param {object[]} g - 参数g为一个对象数组 * @param {string} g.h - 参数g数组中一项的h属性 * @param {string} g.i - 参数g数组中一项的i属性 * @param {string} [j] - 参数j是一个可选参数 */ function foo(a, b, c, d, g, j) { ... }
引号
最外层统一使用单引号。
// not good var x = "test"; // good var y = 'foo', z = '';
变量命名
- 标准变量采用驼峰式命名(除了对象的属性外,主要是考虑到后台返回的数据)
- 'ID'在变量名中全大写
- 'URL'在变量名中全大写
- 常量全大写,用下划线连接
- 构造函数,大写第一个字母
var thisIsMyName; var goodID; var reportURL; var MAX_COUNT = 10; function Person(name) { this.name = name; }
变量声明
一个函数作用域中所有的变量声明尽量提到函数首部,用一个var声明,不允许出现两个连续的var声明。
function doSomethingWithItems(items) { // use one var var value = 10, result = value + 10, i, len; for (i = 0, len = items.length; i < len; i++) { result += 10; } }
函数
- 无论是函数声明还是函数表达式,'('前不要空格,但'{'前一定要有空格;
- 函数调用括号前不需要空格;
- 立即执行函数外必须包一层括号;
- 不要给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 };
数组、对象
- 对象属性名不需要加引号;
- 对象以缩进的形式书写,不要写在一行;
- 数组、对象最后不要有逗号。
// not good var a = { 'b': 1 }; var a = {b: 1}; var a = { b: 1, c: 2, }; // good var a = { b: 1, c: 2 };
括号
下列关键字后必须有大括号(即使代码块的内容只有一行):
if
,else
,for
,while
,do
,switch
,try
,catch
,finally
,with
。// not good if (condition) doSomething(); // good if (condition) { doSomething(); }
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) { ... }
undefined
- 永远不要直接使用undefined进行变量判断;
- 使用typeof和字符串'undefined'对变量进行判断。
// not good if (person === undefined) { ... } // good if (typeof person === 'undefined') { ... }
jshint
- 用'===', '!=='代替'==', '!=';
- for-in里一定要有
hasOwnProperty
的判断; - 不要在内置对象的原型上添加方法,如Array, Date;
- 不要在内层作用域的代码里声明了变量,之后却访问到了外层作用域的同名变量;
- 变量不要先使用后声明;
- 不要在一句代码中单单使用构造函数,记得将其赋值给某个变量;
- 不要在同个作用域下声明同名变量;
- 不要在一些不需要的地方加括号,例:
delete(a.b)
; - 不要使用未声明的变量(全局变量需要加到.jshintrc文件的globals属性里面);
- 不要声明了变量却不使用;
- 不要在应该做比较的地方做赋值;
- debugger不要出现在提交的代码里;
- 数组中不要存在空元素;
- 不要在循环内部声明函数;
- 不要像这样使用构造函数,例:
new function () { ... }
,new Object
;
// not good if (a == 1) { a++; } // good if (a === 1) { a++; } // good for (key in obj) { if (obj.hasOwnProperty(key)) { // be sure that obj[key] belongs to the object and was not inherited console.log(obj[key]); } } // not good Array.prototype.count = function(value) { return 4; }; // not good var x = 1; function test() { if (true) { var x = 0; } x += 1; } // not good function test() { console.log(x); var x = 1; } // not good new Person(); // good var person = new Person(); // not good delete(obj.attr); // good delete obj.attr; // not good if (a = 10) { a++; } // not good var a = [1, , , 2, 3]; // not good var nums = []; for (var i = 0; i < 10; i++) { (function(i) { nums[i] = function(j) { return i + j; }; }(i)); } // not good var singleton = new function() { var privateVar; this.publicMethod = function() { privateVar = 1; }; this.publicMethod2 = function() { privateVar = 2; }; };
其他
- 不要混用tab和space;
- 不要在一处使用多个tab或space;
- 换行符统一用'LF';
- 对上下文this的引用只能使用'_this', 'that', 'self'其中一个来命名;
- 行尾不要有空白字符;
- switch的falling through和no default的情况一定要有注释特别说明;
- 不允许有空的代码块。
// not good var a = 1; function Person() { // not good var me = this; // good var _this = this; // good var that = this; // good var self = this; } // good switch (condition) { case 1: case 2: ... break; case 3: ... // why fall through case 4 ... break; // why no default } // not good with empty block if (condition) { }
- 充分利用html自带语意标签,如