《Web前端开发最佳实践》——2.6　前端代码基本命名规范和格式规范

xiaoxiao2023-08-29 148

本节书摘来自华章计算机《Web前端开发最佳实践》一书中的第2章，第2.6节,作者:党　建更多章节内容可以访问云栖社区“华章计算机”公众号查看。

2.6　前端代码基本命名规范和格式规范

命名规范和格式规范是代码规范中最基本的规范，任何代码的混乱都是从命名和格式的混乱开始的，而意义明确的命名和规整的代码格式则提高了代码的可读性与可维护性，给代码的阅读者和维护者留下了良好的第一印象。命名规范和格式规范没有一个统一的标准，不同的人可能有不同的认识，但是在同一个项目中，必须严格遵守统一的命名和格式规范。以下推荐的规范是在实际项目中认同度较高的代码规范，供读者参考。2.6.1　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”前缀。示例代码：

<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代码简洁。基于这样的原则，可以在页面的公共部分（如页面的头部、尾部以及侧边栏等）、页面经常变化的部分（如广告栏）以及需要后端代码注入的部分添加注释。注释添加的位置在要注释的代码上部并单独占用一行，不要在代码行的后面直接添加。示例代码：

2.6.2　CSS命名规范及格式规范推荐的CSS类的命名规则和元素的id命名规则相似，只是组成类名称的关键字的连接符为中划线（–）。示例代码：

.reader-content-title { ... }

为了避免class命名的重复，命名时取父元素的class名作为前缀。

/* 父元素的样式声明 */ .reader-content { ... } /* 子元素的class名称以父元素中的class名称作为前缀 */ .reader-content-body { ... }

在CSS样式定义中，左大括号放置在选择器的同一行，并和选择器之间添加一个空格分隔，在保证可读性的基础上缩短代码的行数；在样式声明中，属性名称和值之间用一个空格分隔，提高代码可读性。不推荐示例：

/* 不推荐示例：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选择器的注释需要添加在选择器的上一行，而不是和选择器相同一行。示例代码：

/ 注释规范说明：文件头部的文件信息注释 //*!

/ 注释规范说明：模块样式定义的开始和结束 // Content containers start // 注释规范说明：注释需要添加在选择器的上一行，而不是和选择器相同一行 // content title /.reader-content-title { ...}.../ Content containers end /

**2.6.3　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 = '…';

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

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 = (function(){ return {

// reader初始化 Init: function(){ ... }; };

})();

《Web前端开发最佳实践》——2.6 前端代码基本命名规范和格式规范

2.6 前端代码基本命名规范和格式规范

《Web前端开发最佳实践》——2.6　前端代码基本命名规范和格式规范

2.6　前端代码基本命名规范和格式规范