前端规范整理笔记

时间  2020-07-12 标签 前端 规范 整理 笔记

1.代码文件组织结构



2.代码文件的命名

代码文件命名的原则主要是名称须要代表文件对应的模块内容、对应的版本号和文件的格式等，如 jQuery 的文件命名为 jquery-1.8.2.min.js，其中，jquery 代表文件的内容，1.8.2 代表文件的版本号，min 代表此文件为文件的压缩格式版本。若是文件为子模块文件，则在文件名中用点号或短横线来代表父子关系，如 Bootstrap框架中响应式设计模块对应的 CSS 文件的命名为：bootstrap-responsive.css。

3.HTML 命名规范及格式规范

HTML 代码全部的标签名和属性应该都为小写，虽然 HTML 代码是不区分大
小写的，可是 W3C 的规范建议小写；属性值应该使用双引号闭合。
不推荐示例： 
<!-- 不推荐示例：标签名称大写，或者大小写混合；属性值没有用双引号闭合 -->
<IMG src=demo.jpg alt='test' />
推荐示例： 
<!—推荐示例：标签名称小写；属性值用双引号闭合 -->
<img src="demo.jpg" alt="test" />
给全部的关键元素定义元素的 id 和 class，便于和 CSS、JavaScript 交互。由于 id 名称和 class 名称有可能做为检索值用在 JavaScript 代码中，因此命名必定
要规范，这样才能保证不会出现没必要要的重复而致使 Bug 的产生。推荐的作法是根据语义和 DOM 树的层级关系来定义合适的名称，名称中所有使用小写，id 名称中的关键词用下划线（_）链接，class 的关键词用中划线（–） 链接，这样能够最大限度地保证命名的不重复。
不推荐示例： 
<!-- 不推荐示例：命名简单随意，很难保证命名不重复 -->
<div id="Reader">
<div id="introduce" class="Introduce ">
…
</div>
</div>
推荐示例： 
<!-- 推荐示例：根据语义以及上下层级关系定义名称 -->
<div id="reader">
<div id="reader_introduce" class="reader-introduce">
…
</div>
</div>
若是 class 名称仅做为 JavaScript 调用的“钩子”，则可在名称中添加“ js”前缀。
示例代码： 
<!--class 名称仅做为 JavaScript 调用的 " 钩子 "，可在名称中添加 "js" 前缀 -->
<ul id="js_reader_menu">
<li class="menu-toc js-active">Toc</li>
<li class="menu-store js-active">Store</li>
<li class="menu-library">Library</li>
<li class="menu-news">News</li>
</ul>
HTML 代码的层级缩进为 4 个空格。若是元素包含子元素，则此元素对应的起始标签和闭合标签分别单独占用一行。
不推荐示例： 
<!-- 不推荐示例：标签树形层级之间没有缩进或者缩进混乱 -->
<ul>
<li>item1</li><li>item2</li>
<li>item3</li><li>item4</li></ul>
推荐示例： 
<!-- 推荐示例：利用缩进体现元素的层级关系 -->
<ul>
<li>item1</li>
<li>item2</li>
<li>item3</li>
<li>item4</li>
</ul>
给 HTML 代码添加必要的注释。页面 HTML 代码的注释不宜过多，添加的原则是在保证代码维护性的基础上尽可能让 HTML 代码简洁。基于这样的原则，能够在页面的公共部分（如页面的头部、尾部以及侧边栏等）、页面常常变化的部分（如广告栏）以及须要后端代码注入的部分添加注释。注释添加的位置在要注释的代码上部并单独占用一行，不要在代码行的后面直接添加。
示例代码： 
<body>
<!--main header-->
<div id="reader_header">
...
</div>
<!--main content-->
<div id="reader_content">
...
<!-- 动态绑定列表 : toc-->
<ul id="reader_content_toc">
</ul>
</div>
<!--main footer-->
<div id="reader_footer">
...
</div>
</body>

4.CSS 命名规范及格式规范

推荐的 CSS 类的命名规则和元素的 id 命名规则类似，只是组成类名称的关键字的链接符为中划线（ – ）。
示例代码： 
.reader-content-title {
...
}
为了不 class 命名的重复，命名时取父元素的 class 名做为前缀。 
/* 父元素的样式声明 */
.reader-content {
...
}
/* 子元素的 class 名称以父元素中的 class 名称做为前缀 */
.reader-content-body {
...
}
在 CSS 样式定义中，左大括号放置在选择器的同一行，并和选择器之间添加一个空格分隔，在保证可读性的基础上缩短代码的行数；在样式声明中，属性名称和值之间用一个空格分隔，提升代码可读性。

不推荐示例：javascript

/* 不推荐示例：CSS 样式定义中的左大括号单独占一行；样式声明没有缩进或缩进混乱；属性名
称和值之间没有用空格分隔 */
.reader-content-title
{
background:#FFF;
...
}
推荐示例： 
/* CSS 样式定义中的左大括号放置在选择器的同一行；样式声明中属性名称和值之间用一个空格
分隔 */
.reader-content-title {
background: #FFF;
...
}
多个选择器具备相同的样式声明时，每一个选择器应该单独占一行，便于阅读和维护。
不推荐示例： 
/* 不推荐示例：多个选择器具备相同的样式声明时，全部选择器放置于同一行 */
h1,h2,h3 {
font-weight: normal;
line-height: 1.2;
}
推荐示例： 
/* 推荐示例：多个选择器具备相同的样式声明时，每一个选择器应该单独占一行 */
h1,
h2,
h3 {
font-weight: normal;
line-height: 1.2;
}
样式声明的顺序按字母顺序排列，不考虑浏览器前缀。单纯靠手写代码并保证样式声明按照必定的顺序是不现实的。建议使用一些 CSS 美化工具作样式声明排序的工做。
示例代码： 
/* 样式声明的顺序以字母序排列 */
.reader-content-title {
background: #FFF;
border: 1px solid;
-moz-border-radius: 4px;
-webkit-border-radius: 4px;
border-radius: 4px;
color: black;
text-align: center;
}
样式定义按照模块来分组，相同模块的样式定义放在一块儿，不一样模块的定义之间用一个空行分割。
示例代码： 
/* reader header*/
.reader-header-title {
...
}
.reader-header-introduce {
...
}
/*reader footer*/
.reader-footer-copyright{
...
}
.reader-footer-links {
...
}
CSS 中的注释很是重要，能对 CSS 样式起到解释和说明的做用，提升了 CSS代码的可读性。有些开发者可能担忧添加过多的注释会让 CSS 文件行数增多，其实不用担忧，能够在发布网站的时候对 CSS 文件进行压缩，这个过程当中会去掉全部的注释。在 CSS 样式文件中添加注释主要有两种类型：文件头部的文件信息注释和正文中的解释说明性注释。文件信息通常包括文件版本、版权信息以及做者等；解释说明性的注释有给模块的注释和单独给选择器的注释，模块的注释则须要添加注释代表模块样式定义的开始和结束，CSS 选择器的注释须要添加在选择器的上一行，而不是和选择器相同一行。
示例代码： 
/* 注释规范说明：文件头部的文件信息注释 */
/*!
* reader content v1.0
*
* Copyright 2012
* Dual licensed under the MIT or GPL Version 2 licenses.
*
* Designed and built by dangjian
*/
/* 注释规范说明：模块样式定义的开始和结束 */
/* Content containers start */
/* 注释规范说明：注释须要添加在选择器的上一行，而不是和选择器相同一行 */
/* content title */
.reader-content-title {
...
}
...
/* Content containers end */

5.JavaScript 命名规范及格式规范

JavaScript 局部变量命名采用首字母小写，其余单词首字母大写的方式。命名时建议采用有意义的单词命名，不推荐使用标识变量类型的前缀，如 int、str、obj 等。不推荐使用单词缩写命名，变量以缩写命名则下降了其可读性。若是认为变量名太长而使 JavaScript 脚本文件变大，则能够在发布阶段经过 JavaScript 脚本混淆压缩等手段来缩小文件。

不推荐示例：
 
// 不推荐示例：变量命名首字母大写
var ReaderBookmark = 'bookmark';
// 不推荐示例：变量命名意义不明确
var object = {};
// 不推荐示例：变量命名以类型做为前缀
var strName = 'Note';
// 不推荐示例：变量命名使用语义不明确的缩写
var newNT = function(){
…
}
推荐示例：
 
// 推荐示例：变量命名语义明确
var bookmarkDefaultTitle = 'Untitled Bookmark';
如今流行 JavaScript 的面向对象编程，那么就会有公有或私有接口的概念。原则上公有接口的命名为首字母大写，
私有接口的命名为首字母小写。

示例代码：
 
Reader.Content = function(){
// 私有变量
var info, title;
// 私有方法
var getContent = function(){
...
};
return {
// 公有方法
SetTitle: function(contentTitle){
title = contentTitle;
},
// 公有属性
ContentInfo: info
}
}();
jQuery 框架在项目中使用普遍，推荐给 jQuery 类型变量添加“$”做为前缀。
示例代码： 
var $tocTitle = $('.reader-toc-title');
左大括号应该在行的结束位置，而不该该单独一行，由于这样增长了没必要要的行数。应该一直使用大括号括起逻辑块，
即便逻辑只有一行，也应该用大括号
括起来，以便提升代码的可读性和可维护性。

示例代码：
 
// 左大括号应该在行的结束位置，而不该该单独一行
for (var i=0; i<100; i++) {
doSomething(i);
}
// 应该一直使用大括号括起逻辑块，即便逻辑只有一行
var isFound = false;
if (statement) {
isFound = true;
}

JavaScript 中能够用单引号或者双引号定义字符串，可是由于习惯于定义HTML 的元素属性值时使用双引号，而
JavaScript 中又常常包含 HTML 代码，因此字符串定义使用单引号也可方便于在字符串内部包含含有双引号的 HTML 代码。

示例代码：
 
var content = '<span id="main_content">…';

空格的做用是提升代码的可读性，在函数参数的逗号后面使用一个空格，在操做符先后各使用一个空格。
另外，使用一个空行来区分业务逻辑段。

示例代码：
 
doSomething(myChar, 0, 1);
while (x === y){
...
}

JavaScript 语句结束时应该添加一个分号。语句结束是否添加分号这个话题曾经引发很大的讨论，
大名鼎鼎的 Bootstrap 框架中的 JavaScript 语句结束就没有添加分号。著名的框架都不在语句行尾添加分号，
这里有必要简单介绍一下在行尾推荐添加分号的理由。首先来看看 JavaScript 是如何看待分号的。JavaScript 有
自动插入分号的算法，在没有添加分号的 JavaScript 语句的结束处会自动添加一个分号，
可是若是语句的下一行以“[”、“（”、“+”、“-”、“/”开头则不会在此语句后面添加分号。看似合理的设计，
但其实若是应用不慎就会致使一些莫名其妙的错误，以下这个示例是因为自动添加分号而致使的逻辑错误。

错误示例：
 
return
{
a + b
}


按照自动添加分号的算法，会在 return 后面添加一个分号，代码等价于： 
// return 后面会添加一个分号
return ；
{
a + b
}


其结果天然会返回 undefined，而不是指望的值。其实这个诡异的问题能够经过规定左大括号必须放置在前一个语句结尾处的方式来解决。
上面的例子是在不想添加分号的地方被自动添加了分号，而下面的例子则是由于没有在该添加分号的地方添加分号而致使的逻辑错误。

错误示例：
 
var b = function(){
return function(){return 1}
}
var a = b
(function(){
...
})()

根据自动添加分号的算法，“ var a = b”这行语句的后一行代码以左小括号开头，
不会为这行语句自动添加分号，此行代码等价于：
 
var b = function(){
return function(){return 1}
}
var a = b(function(){
...
})()

这彻底背离了代码表达的初衷。固然，能够给以“[”、“（”、“+”、“-”、“/”开头的语句前添加一个分号来避免出现这样的逻辑错误，
可是这也是一种“丑陋”的方案。JavaScript 这种有缺陷的自动添加分号的算法但愿开发者格外当心。
开发者明白这些缺陷则有助于在实际的开发过程当中避免犯错误。尽管在语句结尾添加分号和不添加分号都会有一些问题存在，
可是考虑到大多数开发者已有的习惯，仍是建议给语句的结尾添加分号。由于 JavaScript 代码在前端中是逻辑性最强的，
因此须要添加足够的注释来保证代码的可读性。在 JavaScript 代码中，若是注释未占有多行，那么建议使用//，不推荐使用 /**/。
注释应该单独占用一行，而不是写在和代码相同一行的右边。和 CSS 代码的注释规范类似，JavaScript 代码的注释主要也是文件信息注释和代码逻辑注释。

示例代码：
 
/* 文件头部的文件信息注释 */
/*!
* reader content v1.0
*
* Copyright 2012
* Dual licensed under the MIT or GPL Version 2 licenses.
*
* Designed and built by dangjian
*/
Reader.Content = (function(){
return {
// reader 初始化
Init: function(){
...
};
};
})();
联系我们 沪ICP备13005482号-10