前端开发规范简要概括

前端开发规范简要概括

缩进多少看自己的需求。。

作者：腾讯@AlloyTeam

来源：https://alloyteam.github.io/CodeGuide/

TODO: 阅读【吐血整理的前端代码规范系列 -- css规范】 https://zhuanlan.zhihu.com/p/196345241

文件和目录命名规则

简单来说：都小写，多个单词下划线分割

some_file

目录：有复数结构时，要采用复数命名法。

images

HTML

• 语法 标签内的属性名全小写，多个单词用中划线分割，值用双引号

<img src="images/company_logo.png" alt="Company">

• 引入CSS，JS不需要指明type属性

• 属性的顺序

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

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

  • <a class="..." id="..." data-modal="toggle" href="#">Example link</a>
    

  • class

  • id

  • name

  • data-*

  • src, for, type, href, value , max-length, max, min, pattern

  • placeholder, title, alt

  • aria-*, role

  • required, readonly, disabled

• boolean属性指不需要声明取值的属性 <input type="text" disabled>

• 减少标签数量

CSS,SCSS

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

  .element {
       20px;
      height: 20px;
      
      background-color: red;
  }
  

• 需要空格的情况

  • 属性值前 color: red;
  • 选择器'>', '+', '~'前后 .element > .dialog
  • !important '!'前
  • 注释'/'后和'/'前 /* good */

• 需要空行的情况

  • 文件最后（末尾）保留一个空行
  • }后最好更一个空行
  • 属性之间需要适当空行

• 需要换行的情况

  • '{'后和'}'前

  • 每个属性独占一行

  • 多个规则的分隔符','后

    .element,
    .dialog {
        ...
    }
    

• 注释使用/* */ ,缩进与下一行代码保持一致；

• 命名：类名小写中划线，id采用驼峰式，scss中的变量、函数、混合、placeholder采用驼峰式命名

• 属性声明顺序：相关的属性声明按顺序做分组处理，组之间需要有一个空行。

  .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;
       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进制小写字母 color: #abcdef;

• 属性简写：margin和padding推荐使用简写，其他建议分开声明更加清晰

  .element {
      transition-delay: 2s;
      transition-timing-function: linear;
      transition-duration: 1s;
      transition-property: opacity;
  }
  

• 媒体查询推荐靠近与他们相关的规则，不单独放或者写在最底部

• SCSS相关

  提交的代码中不要有 @debug；

  声明顺序：

  • @extend
  • 不包含 @content 的 @include
  • 包含 @content 的 @include
  • 自身属性
  • 嵌套规则

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

  嵌套最多不能超过5层；

  @extend 中使用placeholder选择器；

  去掉不必要的父级引用符号'&'。

• 其他

  • 不许有空规则
  • 取消小数点前面的0 color: rgba(0, 0, 0, .5);
  • 用 border: 0; 代替 border: none;；
  • 属性值'0'后面不要加单位；
  • 发布的代码中不要有 @import； (不懂咋改)

JavaScript

• 需要空格的情况

  • 运算符前后

  • 代码块'{'前

    var a = {
        b: 1
    };
    

  • 对象的属性值前b: 1

  • for循环，分号后留有一个空格，前置条件如果有多个，逗号后留一个空格

    for (i = 0; i < 6; i++) {
        x++;
    }
    

  • 无论是函数声明还是函数表达式，'{'前一定要有空格

  • 函数的参数之间 function(a, b, c) { ... }

• 需要空行的情况

  • 变量声明后（当变量声明在代码块的最后一行时，则无需空行）
  • 注释前（当注释在代码块的第一行时，则无需空行）
  • 代码块后（在函数调用、数组、对象中则无需空行）
  • 文件最后保留一个空行

• 需要换行的情况

  • 换行的地方，行末必须有','或者运算符； (java中要带着.换行)

  • 代码块'{'后和'}'前和变量赋值后

    var a = {
        b: 1,
        c: 2
    };
    

• 单行注释 双斜线后必须跟一个空格 // 这样 ，缩进与下一行代码保持一致，可位于一个代码行的末尾，与代码间隔一个空格。

• 多行注释 使用情况：难于理解的代码段，业务逻辑强相关的代码，可能存在错误的代码段

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

• 文档注释 TODO 未详细了解

  /**
   * @func
   * @desc 一个带参数的函数
   * @param {string} a - 参数a
   * @param {number} b=1 - 参数b默认值为1
   * @param {string} c=1 - 参数c有两种支持的取值</br>1—表示x</br>2—表示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) {
      ...
  }
  

• 变量命名

  • 标准变量采用驼峰式命名（除了对象的属性外，主要是考虑到cgi返回的数据）

  • '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');
    

• 函数

  • 无论是函数声明还是函数表达式，'('前不要空格，但'{'前一定要有空格；

    函数调用括号前不需要空格；

    立即执行函数外必须包一层括号；

    不要给inline function命名；

    参数之间用', '分隔，注意逗号后有一个空格。

• 数组、对象

  • 对象属性名不需要加引号；

    对象以缩进的形式书写，不要写在一行；

    数组、对象最后不要有逗号。

    var a = {
        b: 1,
        c: 2
    };
    

• 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不要出现在提交的代码里；

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

• 其他

  • 对上下文this的引用只能使用'_this', 'that', 'self'其中一个来命名；

  • 外层统一单引号 let x = z = '<div id="test"></div>';

  • 不要省掉一些括号

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