项目开发规范参考

2018-11-27 本文已影响0人我的钱包瘪瘪的

现有项目的开发规范文档

项目文件命名

基于统一维护和管理，项目文件目前约定使用小驼峰法(如:sleepBand)命名，命名须语义化。
所有的命名不得使用某些关键字、保留字等

文件命名

html文件命名
默认H5新建项目时会在page目录下生成index.html作为整个项目的入口文件。
参照项目文件命名规则。
css文件命名
默认H5新建项目时会在src/css目录下生成style.css作为整个项目的样式文件。
参照项目文件命名规则。css文件可通过：
```
  @import url(path);
```

引入至其他CSS文件中以减少请求。

js文件命名
默认H5新建项目时会在src/js目录下生成appMain.es6作为整个项目的js文件。
文件后缀限制为js、es6、jsx。
若要分开打包js文件,则JS文件的命名必须以app开头，否则会编译入appMain.js文件中。
模块组件目前约定使用大驼峰法(如:SleepChart)命名。
命名需精简,避免a.b.c.d.e的命名。
其他参照项目文件命名规则。js文件可通过：
```
  import React from 'react'; //es6

  var React = require('react'); 
```

等方式来引入其他js文件模块。

HTML规范及约定

标签必须正确闭合
缩进一律采用4个空格
减少标签数量，采用语义化标签
尽量减少使用js手动生成DOM节点
属性名全部小写，自定义属性名需语义化
避免复杂的结构嵌套，灵活使用react及模块处理

CSS规范及约定

禁止空的规则项
分行处理方便维护
每个属性末尾都需加上分号
同一命名空间内不要存在重复规则
css类名需语义化,参照项目文件命名规则。

  /* not good */
  .element {
  }
  .element {
      width :10px;
      width :20px! important;height :20px;
      background-color :red
  }
  /* good */
  .element {
      width: 20px;
      height: 20px;
      background-color: red;
  }

注释统一采用/*something*/处理
css属性可能存在兼容问题或性能问题的慎用
建议不熟悉情况下少使用简写属性，使声明更清晰

  /* not good */
  .element {
      transition: opacity 1s linear 2s;
  }

  /* good */
  .element {
      transition-delay: 2s; /* 过渡延时 */
      transition-timing-function: linear; /* 过渡效果 */
      transition-duration: 1s; /* 过渡周期 */
      transition-property: opacity; /* 过渡属性 */
  }

避免使用通配符
避免直接在行内写样式
建议少使用浮动及定位属性，提升性能
避免4层及以上的选择器，根据由右往左的匹配规则优化选择器

0后面的单位尽量省略，margin,padding尽量使用简写(顺序为:上右下左)

  /* not good */
  * {
      margin: 0;
      padding: 0;
  }

  /* good */
  .element {
      margin: 0;
      padding: 0;
  }

按照css显示属性优化css书写顺序

  /* CSS属性显示顺序 */
  显示属性
  元素位置
  元素属性
  元素内容属性

  /* CSS书写顺序 */
  .element {
      /* 显示属性 */
          display || visibility
          list-style
          position top || right || bottom || left
          z-index
          clear
          float
      /* 自身属性 */
          width max-width || min-width
          height max-height || min-height
          overflow || clip
          margin
          padding
          outline
          border
          background
      /* 文本属性 */
          color
          font
          text-overflow
          text-align
          text-indent
          line-height
          white-space
          vertical-align
          cursor
          content
  }

JS规范

I. 变量申明

变量及函数参数的申明要求语义化。
禁止使用关键字及保留字命名变量及函数参数。
多个变量同时申明采用单var/let/const逗号分隔换行的形式。
使用es6的let/const等来声明不同的变量,常量声明需大写变量。
变量的申明要求写在作用域最上方，避免因变量申明提升引发问题。
state及props等属性申明或使用时需做默认值处理,避免引发js错误。
函数声明只有构造函数才首字母大写，其余函数一律以小写字母开头。
块级区域内的函数声明采用变量赋值的形式防止函数声明提升引发问题。
数组、对象等申明不要采用new Object();的方式，而是采用字面量的方式。

    var once = true,
        fun,
        obj = {
            type : "object"
        },
        updateTime;

    // not good
    var obj = new Object();

    // good
    var obj = {};

    // not good
    function call(once) {
        function test() {
            console.log('Nope.');
        }
    }

    // good
    function call(once) {
        var test;
        test = function test() {
            console.log('Nope.');
        };
    }

II. 简写代码

单行的短if判断建议省略{},减少换行。
条件判断可采用三元表达式。
使用es6语法糖简写代码，如箭头函数、解构赋值等。

适宜的情况下使用短路表达式，如 a || b;但要注意a为undefined、0、null等不同类型引发的取值问题。

  var x = a ? b : c,
      y = d || e,
      z = f && g && h,
      test;
      test = (arg1,arg2)=>{
          //do something
      };

III. 性能优化

禁止使用eval。
优化代码结构，避免代码污染。
调试信息在发布的版本内不可出现。
定时器在不用了的情况下必须及时清除。
不可使用未定义的变量或者定义了变量却不使用。
动画相关的DOM单独模块处理，避免多次渲染其他组件。
尽量避免操作真实DOM,需要的时候使用ReactDOM的API操作真实DOM。

使用局部变量缓存反复查找的对象(包括但不限于全局变量、dom查询结果、作用域链较深的对象)。

  // 缓存对象
  var getComment = function() {
      var dom = $("#common-container"),               // 缓存dom
          appendTo = $.appendTo,                      // 缓存全局变量
          data = this.json.data;                      // 缓存作用域链较深的对象
  }

IV. 注释规范

公共组件在顶部申明所需传值的变量。
函数申明需注明函数作用、所需传值的变量及函数返回。

组件内部在render中使用的属性需给出含义申明(包括但不限于props、state)。

  /**
  * [foo description]
  * @param  {[type]} arg1 [description]
  * @param  {[type]} arg2 [description]
  * @return {[type]}      [description]
  */
  function foo(arg1, arg2){
      //do something
  }

SVN规范

修改及提交项目前须查看是否有新版本未更新，避免冲突。
提交的日志禁止随意输入字符，注明该次提交所更改的内容。
不必要的文件不要提交，添加进ignore list里，比如node_modules。
尽量一天或者一段时间提交一次SVN，不可过于频繁，也不应长时间不提交。
公共文件提交需谨慎，确定不会影响到他人或其他项目再提交。

总结: 考虑了老项目的兼容, 这个是现有项目开发规范基础上做了部分修改

tip

camelCase命名法(驼峰式命名)
开头单词小写，后面单词首字母大写。在Java的官方标准中，Camel命名法被作为主要命名法。使用的很普遍，很多人习惯这种命名方法。示例：userName
PascalCase命名法(帕斯卡命名)
与camelCase命名类似，所有单词首字母大写。有时会有人称为大驼峰式命名。使用很普遍，变量名，方法名等。示例：UserName
kebab-case(短横线命名)
单词以 ‘-’ 短横线连接，常见的class命名方法。示例：user-name
UnderScoreCase(下划线命名)
单词以 ‘_’ 下划线连接，常见文件名的命名。示例：user_name