现有项目的开发规范文档
目录
<span id="命名规则"></span>
项目文件命名
基于统一维护和管理，项目文件目前约定使用小驼峰法(如:sleepBand)命名，命名须语义化。
所有的命名不得使用某些关键字、保留字等
<span id="文件命名"></span>
文件命名
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文件模块。
<span id="HTML规范"></span>
HTML规范及约定
- 标签必须正确闭合
- 缩进一律采用4个空格
- 减少标签数量，采用语义化标签
- 尽量减少使用js手动生成DOM节点
- 属性名全部小写，自定义属性名需语义化
- 避免复杂的结构嵌套，灵活使用react及模块处理
<span id="CSS规范"></span>
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 }
<span id="JS规范"></span>
JS规范
<span id="变量申明"></span>
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.');
};
}
<span id="简写代码"></span>
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 };
<span id="性能优化"></span>
III. 性能优化
禁止使用eval。
优化代码结构，避免代码污染。
调试信息在发布的版本内不可出现。
定时器在不用了的情况下必须及时清除。
不可使用未定义的变量或者定义了变量却不使用。
动画相关的DOM单独模块处理，避免多次渲染其他组件。
尽量避免操作真实DOM,需要的时候使用ReactDOM的API操作真实DOM。
-
使用局部变量缓存反复查找的对象(包括但不限于全局变量、dom查询结果、作用域链较深的对象)。
// 缓存对象 var getComment = function() { var dom = $("#common-container"), // 缓存dom appendTo = $.appendTo, // 缓存全局变量 data = this.json.data; // 缓存作用域链较深的对象 }
<span id="注释规范"></span>
IV. 注释规范
公共组件在顶部申明所需传值的变量。
函数申明需注明函数作用、所需传值的变量及函数返回。
-
组件内部在render中使用的属性需给出含义申明(包括但不限于props、state)。
/** * [foo description] * @param {[type]} arg1 [description] * @param {[type]} arg2 [description] * @return {[type]} [description] */ function foo(arg1, arg2){ //do something }
<span id="SVN规范"></span>
SVN规范
- 修改及提交项目前须查看是否有新版本未更新，避免冲突。
- 提交的日志禁止随意输入字符，注明该次提交所更改的内容。
- 不必要的文件不要提交，添加进ignore list里，比如node_modules。
- 尽量一天或者一段时间提交一次SVN，不可过于频繁，也不应长时间不提交。
- 公共文件提交需谨慎，确定不会影响到他人或其他项目再提交。
总结: 考虑了老项目的兼容, 这个是现有项目开发规范基础上做了部分修改
tip
camelCase命名法(驼峰式命名)
开头单词小写，后面单词首字母大写。在Java的官方标准中，Camel命名法被作为主要命名法。使用的很普遍，很多人习惯这种命名方法。示例：userNamePascalCase命名法(帕斯卡命名)
与camelCase命名类似，所有单词首字母大写。有时会有人称为大驼峰式命名。使用很普遍，变量名，方法名等。示例：UserNamekebab-case(短横线命名)
单词以 ‘-’ 短横线连接，常见的class命名方法。示例：user-nameUnderScoreCase(下划线命名)
单词以 ‘_’ 下划线连接，常见文件名的命名。示例：user_name
