1. 云图网首页
  2. 业界资讯

前端代码相关规范详解编程语言

• 业界资讯

总结一下目前在用的前端代码规范，可作为开发参考

 

一、基础规范

开发规范

项目目录和文件的命名使用小写字母，避免使用大写或驼峰，多个单词以下划线 _ 分隔  如：my_project/cast_detail.js

目录有复数意义的时候，使用复数命名  如 scripts  images

某些第三方插件可直接使用中划线 – 作为文件名单词的间隔 如 bootstrap-datepicker

某些特殊文件可以使用点号 . 作为文件名单词的间隔 如  webpack.config.dev.js  jquery.cookie.min.js

使用有意义的英文单词式命名，避免使用拼音式（如 tupian.png ）命名

 

编辑器设置文件保存格式为 utf-8，以四个空格作为缩进（包括HTML，CSS，JS等），文件末尾空一行，行尾去掉空格

单个函数行数，以不超过一个屏幕为宜（50行左右），超出一个屏幕的，就要考虑拆分成更少的函数

每行代码量不要太长，要适当进行分行（自己也可以在编辑器设置超长自动换行）

在 sublime 中的配置

{ 
    "default_encoding": "UTF-8", 
    "ensure_newline_at_eof_on_save": true, 
    "trim_trailing_white_space_on_save": true, 
    "tab_size": 4, 
    "translate_tabs_to_spaces": true, 
    "word_wrap": "auto" 
}

尽量做到代码的整齐美观

 

HTML规范

在页面开头使用DOCTYPE声明启用标准模式

不要忘了设置语言 language 和编码 charset格式

各层元素应该换行，嵌套的元素节点应该缩进，缩进使用4个空格

属性名统一使用小写，使用中划线 – 作为单词的分隔；属性值统一使用双引号，避免使用单引号

不要在自动闭合标签结尾处使用斜线（HTML5规范 指出他们是可选的，如 <img >）

不要忽略可选的闭合标签（如 </li> ）

<!DOCTYPE html> 
<html lang="zh-CN"> 
    <head> 
        <meta charset="UTF-8"> 
        <title>Page title</title> 
        <!-- 选择性地使用IE兼容模式 --> 
        <meta http-equiv="X-UA-Compatible" content="IE=Edge"> 
    </head> 
    <body> 
        <img src="images/company_logo.png" alt="Company"> 
  
        <h1 class="hello-world">Hello, world!</h1> 
    </body> 
</html>

引入CSS和JS时不需要指名type属性

因为 text/css 和 text/javascript 已经是它们的默认值
另外，时刻牢记应该在 <head>中引入外部CSS，在<body>末尾引入外部JS

<!-- External CSS --> 
<link rel="stylesheet" href="code_guide.css"> 
  
<!-- In-document CSS --> 
<style> 
    ... 
</style> 
  
<!-- External JS --> 
<script src="code_guide.js"></script> 
  
<!-- In-document JS --> 
<script> 
    ... 
</script>

boolean值的属性，不需要声明值的属性

在HTML5中，该属性存在即为true，不存在即为false

<!-- 不建议 --> 
<input type="text" disabled="disabled"> 
<!-- 建议 --> 
<input type="text" disabled> 
  
<!-- 不建议 --> 
<input type="checkbox" value="1" checked="checked"> 
<input type="checkbox" value="1" checked> 
  
<select> 
    <option value="1" selected>1</option> 
</select>

语义化，避免使用不需要的标签，使用有意义的标签

<!-- Not well --> 
<p class="title">我是标题</p> 
<span class="avatar"> 
    <img src="..."> 
</span> 
  
<!-- Better --> 
<h3>我是标题</h3> 
<img class="avatar" src="...">

不要省略表格table 的 thead  tbody

<table> 
    <thead> 
        <tr> 
            <th>ABC</th> 
        </tr> 
    </thead> 
    <tbody> 
        <tr> 
            <td>abc</td> 
        </tr> 
    </tbody> 
</table>

尽量使用HTML实体符而不是直接使用符号

使用<a>标签作为JS事件处理时，统一使用 href=”javascript:;” 伪协议。

因为设置了href之后的<a>标签才具有默认 cursor: pointer 的样式，才能支持Tab切换；

防止点击跳转可以使用 href=”#”，但页面锚点hash会改变；可以使用 javascript:void(0) 但稍长；可以使用事件处理 return false;  event.preventDefault() 但略微麻烦

<!-- Not well --> 
<a href="#">more>></a> 
  
<!-- Better --> 
<a href="javascript:;">more&gt;&gt;</a>

属性应该按照特定的顺序来保证易读性

  • class
  • id
  • name
  • data-*
  • src, for, type, href, value , max-length, max, min, pattern
  • placeholder, title, alt
  • aria-*, role
  • required, readonly, disabled

class是为高可复用组件设计的，所以应处在第一位；

id更加具体且应该尽量少使用，所以将它放在第二位。

<a class="..." id="..." data-modal="toggle" href="#">Example link</a> 
  
<input class="form-control" type="text"> 
  
<img src="..." alt="...">

使用Smarty，Handlebars模板时，注意代码的整洁美观

尽量使用Map映射的结构，而不是条件判断

<!-- Not well --> 
<{if $title == 'one'}> 
<h2>标题一</h2> 
<{elseif $title == 'two'}> 
<h2>标题二</h2> 
<{elseif $title == 'three'}> 
<h2>标题三</h2> 
<{/if}> 
  
<!-- Better --> 
<{assign var="titleText" value=[ 
    'one' => '标题一', 
    'two' => '标题二', 
    'three' => '标题三' 
]}> 
<h2><{$titleText[$title]}></h2>

模板里面符号两端适当地加空格（逗号前不用）

<!-- 逗号后面有空格 --> 
<li <{if in_array($beforeAction.currentUrl, $url)}>class="active"<{/if}> 列表 </li> 
  
<!-- 等号两边有空格 --> 
<{if $abc == 'cdf'}> 
<{/if}>

自定义属性统一使用 data- 前缀

一行标签代码不宜过长，超长时需要适当地按照属性进行分行

但也不是说每个属性都分行

<a class="r-btn r-btn-blue eva-content-btnSave" href="javascript:;" 
   data-commentID="{{commentID}}" 
   data-commentType="{{commentType}}" 
   data-evaID="{{evaID}}" 
   data-roleStaffID="{{roleStaffID}}" 
>确认提交</a>

CSS规范

样式文件头部加上编码规则 统一使用 UTF-8

@charset "UTF-8";

使用四个空格的缩进

每个属性声明末尾都要分号

关于空行

  • 文件最后保留一个空行
  • ‘}’后最好跟一个空行，包括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 { 
    ... 
}

关于空格

以下几种情况不需要空格：

  • 属性名后
  • 多个规则的分隔符’,’前
  • !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 { 
    ... 
}

属性选择器的属性值需要引号，url 里的内容需要引号

.element:after { 
    content: ""; 
    background-image: url("logo.png"); 
} 
  
li[data-type="single"] { 
    ... 
}

类名参考 BEM命名规范

ID以及SASS中相关的变量命名使用小驼峰

/* class */ 
.form-content { 
    ... 
} 
  
/* id */ 
#myDialog { 
    ... 
} 
  
/* 变量 */ 
$colorBlack: #000; 
  
/* 函数 */ 
@function pxToRem($px) { 
    ... 
} 
  
/* 混合 */ 
@mixin centerBlock { 
    ... 
} 
  
/* placeholder */ 
%myDialog { 
    ... 
}

颜色16进制用小写字母，且尽量使用简写形式

/* not good */ 
.element { 
    color: #ABCDEF; 
    background-color: #001122; 
} 
  
/* good */ 
.element { 
    color: #abcdef; 
    background-color: #012; 
}

不要为 0 指定单位，去掉小数点前后的 0

/* 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; 
}

[email protected] ,应使用 <link>方式引入CSS文件

<!-- Not well --> 
<style> 
    @import url("more.css"); 
</style> 
  
<!-- Better --> 
<link rel="stylesheet" href="core.css">

@import 引入的文件不需要开头的 ‘_’ 和结尾的’.scss’；

/* 引入 _variable.scss */ 
  
/* not good */ 
@import "_variable.scss"; 
  
/* good */ 
@import "variable";

尽量将媒体查询的规则靠近与他们相关的规则

不要将他们一起整个放到一个独立的样式文件中，或者丢在文档的最底部

使用前缀属性时，应通过缩进使取值垂直对齐

且私有属性在前，标准属性在后

.selector { 
    -webkit-box-shadow: 0 1px 2px rgba(0, 0, 0, .15); 
            box-shadow: 0 1px 2px rgba(0, 0, 0, .15); 
}

注意属性简写的使用，避免滥用导致覆盖某些样式

如果使用简写，需保证清楚相应顺序的影响，且不会导致其他问题

  • padding
  • margin
  • background
  • border
  • border-radius
  • transition
  • animation
  • font

选择器嵌套层数不宜过长

/* not good */ 
.table > thead > tr > th { … } 
.table > thead > tr > td { … } 
  
/* good */ 
.table > thead > tr { 
    > th { … } 
    > td { … } 
}

尽量不要在HTML中通过 style=… 内联样式

注意属性的声明顺序

相关的属性声明应当归为一组，参考按照下面的顺序排列，另参考

  1. Positioning  定位
  2. Box model  盒模型
  3. Typographic  排版
  4. Visual  外观
  5. 其他
.declaration-order { 
    /* Positioning */ 
    position: absolute; 
    top: 0; 
    right: 0; 
    bottom: 0; 
    left: 0; 
    z-index: 100; 
  
    /* Box-model */ 
    display: block; 
    float: right; 
    width: 100px; 
    height: 100px; 
  
    /* Typography */ 
    font: normal 13px "Helvetica Neue", sans-serif; 
    line-height: 1.5; 
    color: #333; 
    text-align: center; 
  
    /* Visual */ 
    background-color: #f5f5f5; 
    border: 1px solid #e5e5e5; 
    border-radius: 3px; 
  
    /* Other */ 
    opacity: 1; 
}

sublime中可安装使用 CSSComb 插件进行格式转换

前端代码相关规范详解编程语言

  1 { 
  2     // If plugin has trouble finding Node.js, replace this string with path 
  3     // to your `node` bin 
  4     "node-path" : ":/usr/local/bin", 
  5     // Full list of supported options and acceptable values can be found here: 
  6     // https://github.com/csscomb/csscomb.js/blob/master/doc/options.md 
  7     "config": { 
  8         // Whether to add a semicolon after the last value/mixin. 
  9         "always-semicolon": true, 
 10         // Set indent for code inside blocks, including media queries and nested rules. 
 11         "block-indent": "    ", 
 12         // Unify case of hexadecimal colors. 
 13         "color-case": "lower", 
 14         // Whether to expand hexadecimal colors or use shorthands. 
 15         "color-shorthand": true, 
 16         // Unify case of element selectors. 
 17         "element-case": "lower", 
 18         // Add/remove line break at EOF. 
 19         "eof-newline": true, 
 20         // Add/remove leading zero in dimensions. 
 21         "leading-zero": false, 
 22         // Unify quotes style. 
 23         "quotes": "double", 
 24         // Remove all rulesets that contain nothing but spaces. 
 25         "remove-empty-rulesets": true, 
 26         // Set space after `:` in declarations. 
 27         "space-after-colon": " ", 
 28         // Set space after combinator (for example, in selectors like `p > a`). 
 29         "space-after-combinator": " ", 
 30         // Set space after `{`. 
 31         "space-after-opening-brace": "/n", 
 32         // Set space after selector delimiter. 
 33         "space-after-selector-delimiter": "/n", 
 34         // Set space before `}`. 
 35         "space-before-closing-brace": "/n", 
 36         // Set space before `:` in declarations. 
 37         "space-before-colon": "", 
 38         // Set space before combinator (for example, in selectors like `p > a`). 
 39         "space-before-combinator": " ", 
 40         // Set space before `{`. 
 41         "space-before-opening-brace": " ", 
 42         // Set space before selector delimiter. 
 43         "space-before-selector-delimiter": "", 
 44         // Set space between declarations (i.e. `color: tomato`). 
 45         "space-between-declarations": "/n", 
 46         // Whether to trim trailing spaces. 
 47         "strip-spaces": true, 
 48         // Whether to remove units in zero-valued dimensions. 
 49         "unitless-zero": true, 
 50         // Whether to align prefixes in properties and values. 
 51         "vendor-prefix-align": true, 
 52         // Sort properties in particular order. 
 53         "sort-order": [ 
 54                 "font", 
 55                 "font-family", 
 56                 "font-size", 
 57                 "font-weight", 
 58                 "font-style", 
 59                 "font-variant", 
 60                 "font-size-adjust", 
 61                 "font-stretch", 
 62                 "font-effect", 
 63                 "font-emphasize", 
 64                 "font-emphasize-position", 
 65                 "font-emphasize-style", 
 66                 "font-smooth", 
 67                 "line-height", 
 68                 "position", 
 69                 "z-index", 
 70                 "top", 
 71                 "right", 
 72                 "bottom", 
 73                 "left", 
 74                 "display", 
 75                 "visibility", 
 76                 "float", 
 77                 "clear", 
 78                 "overflow", 
 79                 "overflow-x", 
 80                 "overflow-y", 
 81                 "-ms-overflow-x", 
 82                 "-ms-overflow-y", 
 83                 "clip", 
 84                 "zoom", 
 85                 "flex-direction", 
 86                 "flex-order", 
 87                 "flex-pack", 
 88                 "flex-align", 
 89                 "-webkit-box-sizing", 
 90                 "-moz-box-sizing", 
 91                 "box-sizing", 
 92                 "width", 
 93                 "min-width", 
 94                 "max-width", 
 95                 "height", 
 96                 "min-height", 
 97                 "max-height", 
 98                 "margin", 
 99                 "margin-top", 
100                 "margin-right", 
101                 "margin-bottom", 
102                 "margin-left", 
103                 "padding", 
104                 "padding-top", 
105                 "padding-right", 
106                 "padding-bottom", 
107                 "padding-left", 
108                 "table-layout", 
109                 "empty-cells", 
110                 "caption-side", 
111                 "border-spacing", 
112                 "border-collapse", 
113                 "list-style", 
114                 "list-style-position", 
115                 "list-style-type", 
116                 "list-style-image", 
117                 "content", 
118                 "quotes", 
119                 "counter-reset", 
120                 "counter-increment", 
121                 "resize", 
122                 "cursor", 
123                 "-webkit-user-select", 
124                 "-moz-user-select", 
125                 "-ms-user-select", 
126                 "user-select", 
127                 "nav-index", 
128                 "nav-up", 
129                 "nav-right", 
130                 "nav-down", 
131                 "nav-left", 
132                 "-webkit-transition", 
133                 "-moz-transition", 
134                 "-ms-transition", 
135                 "-o-transition", 
136                 "transition", 
137                 "-webkit-transition-delay", 
138                 "-moz-transition-delay", 
139                 "-ms-transition-delay", 
140                 "-o-transition-delay", 
141                 "transition-delay", 
142                 "-webkit-transition-timing-function", 
143                 "-moz-transition-timing-function", 
144                 "-ms-transition-timing-function", 
145                 "-o-transition-timing-function", 
146                 "transition-timing-function", 
147                 "-webkit-transition-duration", 
148                 "-moz-transition-duration", 
149                 "-ms-transition-duration", 
150                 "-o-transition-duration", 
151                 "transition-duration", 
152                 "-webkit-transition-property", 
153                 "-moz-transition-property", 
154                 "-ms-transition-property", 
155                 "-o-transition-property", 
156                 "transition-property", 
157                 "-webkit-transform", 
158                 "-moz-transform", 
159                 "-ms-transform", 
160                 "-o-transform", 
161                 "transform", 
162                 "-webkit-transform-origin", 
163                 "-moz-transform-origin", 
164                 "-ms-transform-origin", 
165                 "-o-transform-origin", 
166                 "transform-origin", 
167                 "-webkit-animation", 
168                 "-moz-animation", 
169                 "-ms-animation", 
170                 "-o-animation", 
171                 "animation", 
172                 "-webkit-animation-name", 
173                 "-moz-animation-name", 
174                 "-ms-animation-name", 
175                 "-o-animation-name", 
176                 "animation-name", 
177                 "-webkit-animation-duration", 
178                 "-moz-animation-duration", 
179                 "-ms-animation-duration", 
180                 "-o-animation-duration", 
181                 "animation-duration", 
182                 "-webkit-animation-play-state", 
183                 "-moz-animation-play-state", 
184                 "-ms-animation-play-state", 
185                 "-o-animation-play-state", 
186                 "animation-play-state", 
187                 "-webkit-animation-timing-function", 
188                 "-moz-animation-timing-function", 
189                 "-ms-animation-timing-function", 
190                 "-o-animation-timing-function", 
191                 "animation-timing-function", 
192                 "-webkit-animation-delay", 
193                 "-moz-animation-delay", 
194                 "-ms-animation-delay", 
195                 "-o-animation-delay", 
196                 "animation-delay", 
197                 "-webkit-animation-iteration-count", 
198                 "-moz-animation-iteration-count", 
199                 "-ms-animation-iteration-count", 
200                 "-o-animation-iteration-count", 
201                 "animation-iteration-count", 
202                 "-webkit-animation-direction", 
203                 "-moz-animation-direction", 
204                 "-ms-animation-direction", 
205                 "-o-animation-direction", 
206                 "animation-direction", 
207                 "text-align", 
208                 "-webkit-text-align-last", 
209                 "-moz-text-align-last", 
210                 "-ms-text-align-last", 
211                 "text-align-last", 
212                 "vertical-align", 
213                 "white-space", 
214                 "text-decoration", 
215                 "text-emphasis", 
216                 "text-emphasis-color", 
217                 "text-emphasis-style", 
218                 "text-emphasis-position", 
219                 "text-indent", 
220                 "-ms-text-justify", 
221                 "text-justify", 
222                 "letter-spacing", 
223                 "word-spacing", 
224                 "-ms-writing-mode", 
225                 "text-outline", 
226                 "text-transform", 
227                 "text-wrap", 
228                 "text-overflow", 
229                 "-ms-text-overflow", 
230                 "text-overflow-ellipsis", 
231                 "text-overflow-mode", 
232                 "-ms-word-wrap", 
233                 "word-wrap", 
234                 "word-break", 
235                 "-ms-word-break", 
236                 "-moz-tab-size", 
237                 "-o-tab-size", 
238                 "tab-size", 
239                 "-webkit-hyphens", 
240                 "-moz-hyphens", 
241                 "hyphens", 
242                 "pointer-events", 
243                 "opacity", 
244                 "filter:progid:DXImageTransform.Microsoft.Alpha(Opacity", 
245                 "-ms-filter://'progid:DXImageTransform.Microsoft.Alpha", 
246                 "-ms-interpolation-mode", 
247                 "color", 
248                 "border", 
249                 "border-width", 
250                 "border-style", 
251                 "border-color", 
252                 "border-top", 
253                 "border-top-width", 
254                 "border-top-style", 
255                 "border-top-color", 
256                 "border-right", 
257                 "border-right-width", 
258                 "border-right-style", 
259                 "border-right-color", 
260                 "border-bottom", 
261                 "border-bottom-width", 
262                 "border-bottom-style", 
263                 "border-bottom-color", 
264                 "border-left", 
265                 "border-left-width", 
266                 "border-left-style", 
267                 "border-left-color", 
268                 "-webkit-border-radius", 
269                 "-moz-border-radius", 
270                 "border-radius", 
271                 "-webkit-border-top-left-radius", 
272                 "-moz-border-radius-topleft", 
273                 "border-top-left-radius", 
274                 "-webkit-border-top-right-radius", 
275                 "-moz-border-radius-topright", 
276                 "border-top-right-radius", 
277                 "-webkit-border-bottom-right-radius", 
278                 "-moz-border-radius-bottomright", 
279                 "border-bottom-right-radius", 
280                 "-webkit-border-bottom-left-radius", 
281                 "-moz-border-radius-bottomleft", 
282                 "border-bottom-left-radius", 
283                 "-webkit-border-image", 
284                 "-moz-border-image", 
285                 "-o-border-image", 
286                 "border-image", 
287                 "-webkit-border-image-source", 
288                 "-moz-border-image-source", 
289                 "-o-border-image-source", 
290                 "border-image-source", 
291                 "-webkit-border-image-slice", 
292                 "-moz-border-image-slice", 
293                 "-o-border-image-slice", 
294                 "border-image-slice", 
295                 "-webkit-border-image-width", 
296                 "-moz-border-image-width", 
297                 "-o-border-image-width", 
298                 "border-image-width", 
299                 "-webkit-border-image-outset", 
300                 "-moz-border-image-outset", 
301                 "-o-border-image-outset", 
302                 "border-image-outset", 
303                 "-webkit-border-image-repeat", 
304                 "-moz-border-image-repeat", 
305                 "-o-border-image-repeat", 
306                 "border-image-repeat", 
307                 "outline", 
308                 "outline-width", 
309                 "outline-style", 
310                 "outline-color", 
311                 "outline-offset", 
312                 "background", 
313                 "filter:progid:DXImageTransform.Microsoft.AlphaImageLoader", 
314                 "background-color", 
315                 "background-image", 
316                 "background-repeat", 
317                 "background-attachment", 
318                 "background-position", 
319                 "background-position-x", 
320                 "-ms-background-position-x", 
321                 "background-position-y", 
322                 "-ms-background-position-y", 
323                 "-webkit-background-clip", 
324                 "-moz-background-clip", 
325                 "background-clip", 
326                 "background-origin", 
327                 "-webkit-background-size", 
328                 "-moz-background-size", 
329                 "-o-background-size", 
330                 "background-size", 
331                 "box-decoration-break", 
332                 "-webkit-box-shadow", 
333                 "-moz-box-shadow", 
334                 "box-shadow", 
335                 "filter:progid:DXImageTransform.Microsoft.gradient", 
336                 "-ms-filter://'progid:DXImageTransform.Microsoft.gradient", 
337                 "text-shadow" 
338         ] 
339     } 
340 }

View json

JavaScript规范

使用四个空格的缩进

不要省略各个情况的分号

var x = 1;   x++;   do {     x++; } while (x < 10);   showTip($tip, function() {   });

字符串统一使用单引号 ‘’

// not good var x = "test";   // good var y = 'foo',     z = '<div id="test"></div>';

用’===’, ‘!==’代替’==’, ‘!=’；

关于命名

  • 使用有意义的命名，默认使用小驼峰式命名（某些参数因数据库设计的原因，也可使用大驼峰，主要参照接口文档）
  • ‘ID’ 在变量名中全大写
  • ‘URL’ 在变量名中全大写
  • ‘Android’ 在变量名中大写第一个字母
  • ‘iOS’ 在变量名中小写第一个，大写后两个字母
  • 常量全大写，用下划线连接
  • 构造函数，大写第一个字母
  • jQuery对象必须以 ‘$’ 开头命名
var thisIsMyName;   var goodID;   var reportURL;   var AndroidVersion;   var iOSVersion;   var MAX_COUNT = 10;   function Person(name) {     this.name = name; }   // not good var body = $('body');   // good var $body = $('body');

关于空格

以下几种情况不需要空格：

  • 对象的属性名后
  • 前缀一元运算符后
  • 后缀一元运算符前
  • 函数调用括号前
  • 无论是函数声明还是函数表达式，'(‘ 前不要空格
  • 数组的 ‘[‘ 后和 ‘]’ 前
  • 对象的 ‘{‘ 后和 ‘}’ 前
  • 运算符 ‘(‘ 后和 ‘)’ 前

以下几种情况需要空格：

  • 二元运算符前后
  • 三元运算符 ‘?:’ 前后
  • 代码块 ‘{‘ 前
  • 下列关键字前：else, while, catch, finally
  • 下列关键字后：if, else, for, while, do, switch, case, try, catch, finally, with, return, typeof
  • 单行注释 ‘//’ 后（若单行注释和代码同行，则 ‘//’ 前也需要），多行注释 ‘*’ 后
  • 对象的属性值前
  • for 循环，分号后留有一个空格，前置条件如果有多个，逗号后留一个空格
  • 无论是函数声明还是函数表达式，'{‘ 前一定要有空格
  • 函数的参数之间
// 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 
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; 
if (typeof a === "undefined" || 
typeof a.b === "undefined" || 
a.c !== true) { 
url = "www.www.www"; 
} else { 
url = "www.www"; 
} 
// 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;

代码注释参考注释规范

简化变量的声明，避免多个连续的 var  let 声明

// not good 
let a = 1; 
let b = 2; 
let c = 3; 
// good 
let a = 1, 
b = 2, 
c = 3;

关于数组和对象的使用

简单的条件语句应该转换为对象映射，使用字面量声明而不是实例化声明

对象属性名默认不加引号，如果必要（属性名带中划线 – ）时加引号，需要保持统一

对象以缩进的形式书写，不要写在一行（ES6的解构视情况而定，但一行也不宜过长）

末尾一项不要留逗号

// not good 
if (a === 1) { 
b = 'a'; 
} else if (a === 2) { 
b = 'aa'; 
} else if (a === 3) { 
b = 'aaa'; 
} else { 
b = 'b'; 
} 
// good 
var obj = { 
1: 'a', 
2: 'aa', 
3: 'aaa' 
}; 
b = obj[a] || 'b'; 
// not good 
function Book() { 
} 
var book = new Book(); 
book.name = 'book1'; 
book.ages = new Array(1, 2, 3); 
// good 
var book = { 
name: 'book1', 
ages: [1, 2, 3] 
}; 
// not good 
var a = { 
'b': 1 
}; 
var a = { 
b: 1, 
'c-d': 2 
}; 
var a = {b: 1}; 
var a = { 
b: 1, 
c: 2, 
}; 
// good 
var a = { 
'b': 1, 
'c-d': 2 
}; 
var a = { 
b: 1, 
c: 2 
};

if  while try 等携带的括号不可省略

包括 if, else, for, while, do, switch, try, catch, finally, with 等，应该统一使用括号包裹成块，即使只有一行

// not good 
if (condition) 
doSomething(); 
// good 
if (condition) { 
doSomething(); 
}

不要直接使用 undefined 进行变量的判断

// not good 
if (person === undefined) { 
... 
} 
// good 
if (typeof person === 'undefined') { 
... 
}

使用类型转换，短路断路运算  ||  && ，三目运算符

这里不包括使用 == 的类型转换

短路断路和三目仅在简单的逻辑里使用，避免嵌套负杂的多层，且应添加适当的注释说明

// not good 
if ($elem.length === 0) { 
showTip(); 
} 
// good 
if (!$elem.length) { 
showTip(); 
} 
// better 
!$elem.length && showTip(); 
// not good 
if (a) { 
b = a; 
c = 10; 
} else { 
b = 100; 
c = 100; 
} 
// good 
b = a || 100; 
c = a ? 10 : 100;

for-in 里一定要有hasOwnProperty的判断

for (key in obj) { 
if (obj.hasOwnProperty(key)) { 
console.log(obj[key]); 
} 
}

上下文 this 的别名，仅仅使用 that  _this  self 

避免使用 me

switch 中 应该设置 default

如果不设置，需要写明注释

// good 
switch (condition) { 
case 1: 
case 2: 
... 
break; 
case 3: 
... 
// why fall through 
case 4 
... 
break; 
// why no default 
}

jQuery的链式调用分层应换行缩进

// not good 
$elem.addClass('abc').hide().find('h1').text('abc'); 
// good 
$elem.addClass('abc').hide() 
.find('h1').text('abc');

尽量使用函数声明，而不是函数表达式

// not good 
var foo = function () { 
// do something 
} 
// good 
function foo () { 
// do something 
}

关于字符串，HTML元素的拼接

注意换行和缩进，拼接HTML的时候注意性能，ES6环境中应该使用模板字符串

// not good 
var str = '<div><p>abc<p><p>aaa<span>sss</p></div>'; 
// good 
var str = '' + 
'<div>' + 
'<p>abc<p>' + 
'<p>aaa' + 
'<span>sss' + 
'</p>' + 
'</div>'; 
// ES6中 
// not good 
for (var i = 0; i < 10; ++i) { 
$('select').append('<option value="' + i + '">选项' + （i + 1）+ '</option>' ); 
} 
// good 
var $select = $('select'); 
option = []; 
for (var i = 0; i < 10; ++i) { 
option.push(`<option value="${i}">选项${i + 1}</option>`); 
} 
$select.html(option.join(''));

尽量不设置全局变量

如果设置全局变量，变量名应带有”全局“相关的字样

var globalMsg = ''; 
var globalVariable = { 
msg: 'aa', 
number: 12 
};

 

二、CSS命名规范

BEM规范

 

三、注释规范

好的注释不仅能够表达”是什么“，还能表达”为什么“

HTML注释规范

注释以字符 <!– 开始，以字符 –> 结束

注释独占一行，置于代码上方，左右闭合前保留一个空格

对于模块（或者某个代码块）注释，需要增加 首（S）尾（E）标识，模块之间相隔一行

<!-- Comment Text --> 
<div>...</div> 
<!-- S Comment Text 1 --> 
<div class="mod_a"> 
... 
</div> 
<!-- E Comment Text 1 --> 
<!-- S Comment Text 2 --> 
<div class="mod_b"> 
... 
</div> 
<!-- E Comment Text 2 -->

Smarty 前端模板注释规范

注释以字符 <{* 开始，以字符 *}> 结束

当只是作为代码意义标识的时候，统一使用HTML的注释规则 <!–   comment –>

当需要注释不执行某个Smarty部分时，需要遵循Smarty的注释规则（建议首尾独占一行，注释的文字在首行之后，与 <{* 间隔一个空格，如下）

<!-- S 头部模块 -->  
<link .....> 
<{include file='./header.tpl'}> 
<!-- E 头部模块 -->  
<{* 暂不引人 
<h1><{block name="page_header"}><{/block}></h1> 
*}>

CSS/SASS 注释规范

注释以字符 /* 开始，以字符 */ 结束，左右闭合前保留一个空格，建议一行注释

也可在一行代码后面，注意与代码间有空格

/* 某个表单 */ 
.search-form { 
&__left { 
position: absolute; /* 定位 */ 
} 
}

JS 注释规范

单行注释

使用双斜线 // ，双斜线后带一个空格，双斜线与下一行缩进一致

可位于代码行的末尾，需与代码间隔一个空格

if (condition) { 
// if you made it here, then all security checks passed 
    allowed(); 
} 
var zhangsan = 'zhangsan'; // one space after code

多行注释

注释以字符 /* 开始，以字符 */ 结束，至少三行，参考以下例子

建议在难以理解的代码块，逻辑性强，特殊处理的地方使用

/* 
* one space after '*' 
*/ 
var x = 1;

文档注释

JSDoc规范 JSDoc用于根据规范的JS注释自动生成对应的API文档，如果不需要生成文档，只需遵循以下常用规范

注释前要空一行，建议在所有函数，类，常量中使用

常用的几个标签：@author  @license  @copyright  @param  @return   @example  @version  @class  @constructor  @type  @constant  @todo ，更多标签参考

@param中的 {[type]} 使用小写开头，多个type使用 | 分隔，且尽量保持各项的对齐

常用的type类型有 boolean（布尔值）， number（数字），string（字符串），array（数组）, object（对象）, function（函数），jqueryObject（jQuery对象），htmlObject（HTML元素对象）等，也可自定义

/** 
* 最大次数 
* @constant {number} 
*/ 
const MAX_TIMES = 10; 
/** 
* 一个自定义类 
* @version 1.0.0 
* @class MyClass 
* @constructor 
*/ 
function MyClass() { 
// 名字 
this.name = 'defaultName'; 
} 
MyClass.prototype = { 
constructor: MyClass, 
/** 
* 获取名字 
* @return {string} 名字 
*/ 
getName: function() { 
return this.name || ''; 
}, 
/** 
* 设置名字 
* @param  {string|array} name 名字，多个名字将以空格分隔 
* @example 
* setName('ppk') 
* setName(['a', 'b']) 
*/ 
setName: (name) => { 
this.name = typeof name === 'string' ? name : name.join(' '); 
} 
}; 
/** 
* 异步获取 
* @param  {string}     url            连接 
* @param  {object}     data           数据 
* @param  {function}   cb             成功的回调 
* @param  {function}   errorCb        失败的回调 
* @param  {function}   exceptionCb    异常的回调   
* @param  {boolean}    noLayerLoading 是否显示加载图标 
*/ 
function ajax(url, data, cb, errorCb, exceptionCb, noLayerLoading) { 
}

JSX 模板注释规范

JSX其实只是JS的语法糖，所以注释类似JS

一般的注释为以字符 {/* 开始，以字符 */} 结束

let Content = ( 
<Nav> 
{/* 我是注释 */} 
<Person name={window.isLoggedIn ? window.name : ''} /> 
</Nav> 
);

 

 

 

参考  Code Guide by AlloyTeam    Aotu.io 

原创文章，作者：奋斗，如若转载，请注明出处：https://blog.ytso.com/13178.html

赞 (0)
0
上一篇 2021年7月19日
下一篇 2021年7月19日

相关推荐

发表回复

登录后才能评论