前端编码规范

Love The Way You Lie 2022-04-17 07:17 245阅读 0赞

为了统一代码风格，提高代码的可读性和可维护性，特制定此编码规范。

**统一规则**  
变量命名使用英文单词，不允许使用汉语拼音。  
代码块缩进使用 4 个空格，不建议使用 Tab 键缩进。  
文件名不允许使用中文字符，建议文件名仅包含大小写字母、数字、英文中划线（-）和英文下划线（\_）。  
在使用某个文件的时候，在代码中必须准确的使用该文件的名称，大小写要正确。因为开发环境是 Windows 的同学，系统本身对于文件名是大小写是不敏感的，而测试与生产环境是 Linux 系统，大小写敏感，如果使用文件时拼写的大小写不准确，会导致开发过程中没问题，但是上到测试和生产的时候发生错误。  
源代码文本文件保存一律采用 UTF-8 的格式，并且不能包含 BOM。  
类名、变量名应为名词。方法名、函数名应为动词或者动宾结构。  
HTML 编码规范  
标签名称小写  
正确：

<div>这里是一个 DIV 标签。</div>

错误：

<DIV>这里是一个 DIV 标签。</Div>

**属性名小写，属性值使用双引号引起来**  
正确：

错误：

**确保页面的元素 ID 唯一性**  
在一个页面中，要保证元素 ID 唯一。  
**非标准属性名，使用 data- 前缀，并且多个单词之间使用中划线分隔**  
正确：

<div id="div-1" data-non-standard-attribute="my-value">这个 DIV 具有一个非标准的属性。 </div>

错误：

<div id="div-1" nonstandardattribute="my-value">这个 DIV 具有一个非标准的属性。</div>

正确的 DOCTYPE  
正在筹划中的云班课 Web 2.0 版本中，我们强制用户使用新版本支持 HTML5 的浏览器。强制支持 HTML5 的页面要正确的使用 DOCTYPE。

HTML 源代码的第一行应该为：

<!DOCTYPE html>

**禁止直接使用元素属性设置元素的大小和位置**  
元素的大小和位置实际上属于展示层面，在 HTML5 规范中，HTML 负责数据，CSS 负责展示。所以除了几个特殊的元素（<canvas>），其他元素的大小和位置一律使用 CSS 样式来完成，禁止只用元素的 width, height 等属性来指定。

正确：

错误：

**需要闭合的标签，必须闭合**  
对于需要闭合的 HTML 标签，必须进行闭合标记，哪怕标签中是没有任何内容。

正确：

错误：

<div/>

**对于无需自闭合的标签，不允许自闭合**  
正确：

错误：

**禁止 img 的 src 取值为空**  
延迟加载的图片也要增加默认的 src

正确：

错误：

**JavaScript 编码规范**  
命名总体规范  
变量命名，首字母小写驼峰法：variableNameLikeThis  
函数命名，首字母小写驼峰法：functionNameLikeThis  
类命名，首字母大写驼峰法：ClassNameLikeThis  
常量，全大写，下划线分隔：CONST\_LIKE\_THIS  
变量声明  
变量必须使用 var 声明：

正确：

var defaultScore = 1;
    var users = [];

错误：

defaultScore = 1;
    users = [];

**总是使用分号**  
虽然 JavaScript 允许在不影响代码含义的前提下省略行尾分号（;），但是要求必须使用分号。

正确：

var domObject = document.getElementById("div-1");
    domObject.onClick = function(evt) {
        // Your code goes here
    };

错误：

var domObject = document.getElementById("div-1");
    domObject.onClick = function(evt) {
        // Your code goes here
    }

// 上面的代码是一个赋值表达式，所以不能省略末尾的分号  
**合理使用空格和空行**  
赋值运算、逻辑运算符两侧使用空格：var someVar = 1;， if(foo> bar)  
函数参数之间使用空格：someFunc(param1, param2, param3);  
for 循环中的三段之间空格：for (var i = 0; i < 10; i++)  
**花括号**  
左花括号跟随上一行代码，右花括号独占一行。如果是内嵌匿名函数，可以把花括号和圆括号写在一行。

例子 1:

for (var i = 0, n = 10; i < n; i++) {
        // your code goes here
    }

例子 2：

$(domObject).bind("click", function(evt) {
        // your code goes here
    });

类注释  
每个类的定义都要附带一份注释，描述类的功能和用法。也需要说明构造器参数。如果该类继承自其它类，应该使用 @extends 标记。如果该类是对接口的实现，应该使用 @implements 标记。

/**
     * Class making something fun and easy.
     * @param {string} arg1 An argument that makes this more interesting.
     * @param {Array.<number>} arg2 List of numbers to be processed.
     * @constructor
     * @extends {goog.Disposable}
     */
    project.MyClass = function(arg1, arg2) {
      // ...
    };
    goog.inherits(project.MyClass, goog.Disposable);

**方法注释**  
提供参数的说明。使用完整的句子，并用第三人称来书写方法说明。

/**
     * Converts text to some completely different text.
     * @param {string} arg1 An argument that makes this more interesting.
     * @return {string} Some return value.
     */
    project.MyClass.prototype.someMethod = function(arg1) {
      // ...
    };
    
    /**
     * Operates on an instance of MyClass and returns something.
     * @param {project.MyClass} obj Instance of MyClass which leads to a long
     *     comment that needs to be wrapped to two lines.
     * @return {boolean} Whether something occured.
     */
    function someMethod(obj) {
      // ...
    }

常用的注释标记及其说明  
@param  
@param \{Type\} 变量名 描述

/**
     * Queries a Baz for items.
     * @param {number} groupNum Subgroup id to query.
     * @param {string|number|null} term An itemName,
     *     or itemId, or null to search everything.
     */
    goog.Baz.prototype.query = function(groupNum, term) {
      // ...
    };

@return  
@return \{Type\} 描述

/**
     * @return {string} The hex ID of the last item.
     */
    goog.Baz.prototype.getLastId = function() {
      // ...
      return id;
    };

@author  
@author [youname@yourdomain.com][youname_yourdomain.com]  
@type  
@type Type  
@type \{Type\}

/**
     * The message hex ID.
     * @type {string}
     */
    var hexId = hexId;

**CSS 编码规范**  
命名规范  
CSS 中的类、ID 等选择器的名字一律小写字母，多个单词之间使用短横线（-）分隔，例如：

正确：

.user-not-login {
        width: 10px;
        background-color: gray;
    }

错误：

.usernotlogin {
        width: 10px;
        background-color: gray;
    }
    
    .userNotRegister {
        width: 10px;
        background-color: gray;
    }

**大花括号**  
样式内容较少的，可以将选择器、花括号以及样式写在一行。样式内容较多的，建议写在多行，并且左大花括号和选择器位于一行。

选择器名称和左大花括弧之间保留一个空格：

正确：

.thin-line { border: 1px solid gray; }
    .hint-box {
        background-color: yellow;
        color: #646464;
        font-size: 12px;
        line-height: 150%;
    }

[youname_yourdomain.com]: mailto:youname@yourdomain.com