项目README文件的书写示例

前言

一个优秀的项目，它的readme.md的文件肯定编写的特别规范，对用户 功能及体验 对开发者 可维护。如何书写一个好的readme文件呢，下文是以小程序 wepy框架开发的项目为例

## 规范

一、 样式还原按设计稿

1. 基准机型 100%还原，其他机型做适配

2. 主题字体、颜色等设置全局变量

3. 长度单位 rpx (不再设定变量转换)

二、内容及逻辑按需求文档(wiki)

三、命名及代码规范

1. 英文语义化命名，示例：someName, some-name

2. 属性、方法、变量名，小驼峰法，示例：var someName = ‘miniApp’

3. Class 样式类，中横线法，示例：

4. 图片文件名，中横线法， 示例：some-name.png

5. Wepy 文件命名，组件大驼峰，示例：InfoIdCard.wpy; 页面命名，小驼峰，示例：myPolicy.wpy

6. 代码 eslint 规范要求

7. 信息录入组件，最小单元为具体信息组件，props 属性传参（同角色属性）统一命名(详见七)

8. props 属性定义，采用 value 对象结构，示例： value: {default: ‘’, type: String}

四、目录结构

1. 公有方法放置 utils 下

2. 数据类放置 data 下

3. 创建页面定义在 pages 下

4. 调取接口公共方法放在 api 下

5. 创建组件放在 componenes 下

6. 图片和 less 样式放在 assets 下

7. 页面混合数据放在 mixins 下

8. mock 数据放在 mock 下

9. wxs 文件放在 wxs 下

五、分支规范

1. 稳定分支 master

2. 主开发分支 develop

3. 自建分支 feature/somename

4. bug 类分支 fixbug/somename

六、appid=wx870cf1972d28939c

七、录入型 props 统一命名 list

1. value: 信息采集值

2. title: 组件左侧信息描述

3. isDisabled: 禁止修改状态

4. placeholder： input 项 placeholder

5. selectList: 选择项的 list

八、缓存数据清单

1. query: 启动页参数，代理人、相关信息
2. userInfo: 微信用户相关信息
3. productData： 产品首页图文信息的数据
4. userInfoList： 用户列表
5. selectedUserList： 已选用户

九、issue

1. 年收入滑块来回滑动出现问题，只是点击触发貌似没有

2. 纳税人弹窗 radio 按钮样式错位，这里最好重新写这个弹窗，不使用原生小程序 radio 去实现，原生小程序 radio 样式不好把控

3. 某些页面数据不渲染

4. 人员信息页面不渲染受益人列表

5. 拍照后压缩到一定值后 quality 不生效

6. 人员信息页 点下一步， 如投保人信息不完整， 最好将更多展示

7. 健康告知 勾选左下角 同意的触发区域太小

8. 职业弹窗 回显，及地址的详情 层级高于弹窗

十、代码规范 在 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文件夹下为分包，主要包括投保流程页面