前言
一个优秀的项目,它的readme.md的文件肯定编写的特别规范,对用户 功能及体验 对开发者 可维护。如何书写一个好的readme文件呢,下文是以小程序 wepy框架开发的项目为例
## 规范
一、 样式还原按设计稿
-
基准机型 100%还原,其他机型做适配
-
主题字体、颜色等设置全局变量
-
长度单位 rpx (不再设定变量转换)
二、内容及逻辑按需求文档(wiki)
三、命名及代码规范
-
英文语义化命名,示例:someName, some-name
-
属性、方法、变量名,小驼峰法,示例:var someName = ‘miniApp’
-
Class 样式类,中横线法,示例:
-
图片文件名,中横线法, 示例:some-name.png
-
Wepy 文件命名,组件大驼峰,示例:InfoIdCard.wpy; 页面命名,小驼峰,示例:myPolicy.wpy
-
代码 eslint 规范要求
-
信息录入组件,最小单元为具体信息组件,props 属性传参(同角色属性)统一命名(详见七)
-
props 属性定义,采用 value 对象结构,示例: value: {default: ‘’, type: String}
四、目录结构
-
公有方法放置 utils 下
-
数据类放置 data 下
-
创建页面定义在 pages 下
-
调取接口公共方法放在 api 下
-
创建组件放在 componenes 下
-
图片和 less 样式放在 assets 下
-
页面混合数据放在 mixins 下
-
mock 数据放在 mock 下
-
wxs 文件放在 wxs 下
五、分支规范
-
稳定分支 master
-
主开发分支 develop
-
自建分支 feature/somename
-
bug 类分支 fixbug/somename
六、appid=wx870cf1972d28939c
七、录入型 props 统一命名 list
-
value: 信息采集值
-
title: 组件左侧信息描述
-
isDisabled: 禁止修改状态
-
placeholder: input 项 placeholder
-
selectList: 选择项的 list
八、缓存数据清单
- query: 启动页参数,代理人、相关信息
- userInfo: 微信用户相关信息
- productData: 产品首页图文信息的数据
- userInfoList: 用户列表
- selectedUserList: 已选用户
九、issue
-
年收入滑块来回滑动出现问题,只是点击触发貌似没有
-
纳税人弹窗 radio 按钮样式错位,这里最好重新写这个弹窗,不使用原生小程序 radio 去实现,原生小程序 radio 样式不好把控
-
某些页面数据不渲染
-
人员信息页面不渲染受益人列表
-
拍照后压缩到一定值后 quality 不生效
-
人员信息页 点下一步, 如投保人信息不完整, 最好将更多展示
-
健康告知 勾选左下角 同意的触发区域太小
-
职业弹窗 回显,及地址的详情 层级高于弹窗
十、代码规范 在 codeValue.js
/**
* 代码价值:
* 对用户 功能及体验
* 对开发者 可维护
*/
function codeValue() { }
// 一、 命名规范
/**
* 语义化命名 见名知意
* 注释辅助
*/
codeValue.nameStandard = {
'1': '语义化命名 见名知意',
'2': '注释辅助'
}
// 反例
var legal0, legal1
function checkCor() { }
// 正例
var isSameInsure, isDiffInsure
function checkColor() { }
// 二、最小代码块封装
codeValue.minFunction = function (val) {
return val + 1
}
// 反例
function getPolicyPlan() {
// 请求被保人远程的数据
let that = this
let { cusNo } = JSON.parse(sessionStorage.getItem('query')) || {}
this.$axios.get(config.signRemote + `/${cusNo}`)
.then(res => {
let data = res.data
that.infoList[0].name = data.applicant.name
that.infoList[0].idType = data.applicant.idType
that.infoList[0].idNo = data.applicant.idNo
that.infoList[0].cellphone = data.applicant.cellphone
that.infoList[1].name = data.insuredWraper.name
that.nameLength = data.insuredWraper.name.length
that.infoList[1].idType = data.insuredWraper.idType
that.infoList[1].idNo = data.insuredWraper.idNo
that.infoList[1].cellphone = data.insuredWraper.cellphone
that.riseCodeInfo = data.inspWrapers // 险种信息
that.totalPremium = data.premium // 总保费
if (!data.orderNumbers) {
that.benifityList = []
} else {
for (let i = 0; i < data.orderNumbers.length; i++) {
let beneficiaries = data.orderNumbers[i].beneficiaries
for (let j = 0; j < beneficiaries.length; j++) {
let obj = {}
obj.orderId = data.orderNumbers[i].orderId
obj.name = beneficiaries[j].name
obj.ratioOfBenefit = beneficiaries[j].ratioOfBenefit + '%'
obj.idType = beneficiaries[j].idType
obj.idNo = beneficiaries[j].idNo
that.benifityList.push(obj)
}
}
}
})
}
// 正例
function renderPolicy() {
this.renderInsure()
this.renderInsued()
//...
}
// 三、公共方法抽离到utils
// 生日年龄相关 日期时间相关
// utils/getAge.js
// getAget() {}
// 团队开发 约定,避免相同模块多处定义
// 四、 一个代码块中 避免重复使用对象索引值
// 反例
this.currentUserList[this.currentTab].province = provinceValue;
this.currentUserList[this.currentTab].city = cityValue;
this.currentUserList[this.currentTab].area = areaValue;
// 正例
var currentUser = this.currentUseList[this.currentTab]
currentUser.name = name;
currentUser = { ...currentUser, city, province, area }
// 五、明明白白使用this
// 有意义的that
// 反例
var that = this
that.name = '444'
// 正例一
var that = this
setTimeout(function () { that.name = '666' })
// 正例二
setTimeout(() => { this.name = '555' })
// 六、接口状态处理
// 1. 接口成功 200 => 接口业务逻辑成功 || 业务逻辑失败
// 2. 接口失败 非200
if (res.statusCode == 200) {
// 接口success
if (res.data.status) {
// 业务 success
} else {
// 业务 fail
}
} else {
// fail
}
// 七、 获取布尔值
// 反例
codeValue.isTens = function () {
if (num % 10 === 0) {
return true
} else {
return false
}
}
// 正例
codeValue.isTens = function () {
return num % 10 === 0
}
// 八、分流逻辑 结构设计
// 逻辑分流的几种方式
// 条件语句
// switch语句
// 对象结构
// 反例
if (res.data == 200) {
// do someting
} else if (res.data == 201) {
// do someting
} else if (res.data == 202) {
// do someting
}
// 正例子
var data = {
'200': '',
'201': '',
'202': ''
}
datap[val]
// 九、 冗余代码块
import { log } from 'util';
import { setTimeout } from 'timers';
// 十、 == && ===
// 十一、环境变量
// npm run XX 中设置变量
var env = process.env.NODE_DEV
var isProduction = env === 'production'
if (isProduction) doSomething
十一、小程序分包
\1. 主包
pages文件夹下为主包,主要包括微店页面和productInfo/seedEntrance
\2. 分包
insure文件夹下为分包,主要包括投保流程页面