项目README文件的书写示例

前言

一个优秀的项目，它的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, legal1function checkCor() { }
// 正例
var isSameInsure, isDiffInsurefunction checkColor() { }// 二、最小代码块封装
codeValue.minFunction = function (val) {return val + 1
}
// 反例
function getPolicyPlan() {// 请求被保人远程的数据let that = thislet { cusNo } = JSON.parse(sessionStorage.getItem('query')) || {}this.$axios.get(config.signRemote + `/${cusNo}`).then(res => {let data = res.datathat.infoList[0].name = data.applicant.namethat.infoList[0].idType = data.applicant.idTypethat.infoList[0].idNo = data.applicant.idNothat.infoList[0].cellphone = data.applicant.cellphonethat.infoList[1].name = data.insuredWraper.namethat.nameLength = data.insuredWraper.name.lengththat.infoList[1].idType = data.insuredWraper.idTypethat.infoList[1].idNo = data.insuredWraper.idNothat.infoList[1].cellphone = data.insuredWraper.cellphonethat.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].beneficiariesfor (let j = 0; j < beneficiaries.length; j++) {let obj = {}obj.orderId = data.orderNumbers[i].orderIdobj.name = beneficiaries[j].nameobj.ratioOfBenefit = beneficiaries[j].ratioOfBenefit + '%'obj.idType = beneficiaries[j].idTypeobj.idNo = beneficiaries[j].idNothat.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) {// 接口successif (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文件夹下为分包，主要包括投保流程页面

项目README文件的书写示例相关推荐

软件项目规范（1）：README文件的基本写作规范
看Github的开源项目,我们都能看到README.md文件的身影. 有不少同学都喜欢将自己的项目上传到Git托管起来,但是总能发现一个问题:明明自己这个项目挺有市场的啊,怎么这个代码放上去,就显得很 ...
如何书写项目README.md文档
背景编写一个项目的 README 就像是写一本书的序言一样,一个好的项目不应该仅仅只有一份高质量代码,同时更应该有一份高质量的文档.而对使用者来说,一份好的文档能够节省大量的时间. 文档结构基本选 ...
java项目README.MD文件模板
java项目README.MD文件模板项目简介: 用一两句话简单描述该项目所实现的业务功能: 技术选型: 后端技术栈 springboot mybaits jwt 数据库关系型数据库 mysql ...
论文LaTeX、项目README：无脑套用格式、开源模板最高10万赞
公众号关注 "视学算法" 设为 "星标",消息即可送达! 来自 | GitHub 转自 | 机器之心参与 | Jamin.思.一鸣即使是最具创意性的机 ...
README文件编写
一直对README.md文件颇为感兴趣,每个工程根目录都要放置. md是markdown的缩写,markdown是一种编辑博客的语言.用惯了可视化的博客编辑器(比如CSDN博客,囧),这种编程式的博客 ...
eclipse 创建maven 项目动态web工程完整示例
需求表均同springmvc案例此处只是使用maven 注意,以下所有需要建立在你的eclipse等已经集成配置好了maven了,说白了就是新建项目的时候已经可以找到maven了没有的话需要安装m ...
Unity Application Block-配置文件的使用-示例（附×××）
Unity Application Block-配置文件的使用-示例(附×××) 关于在ASP.NET 中使用Unity Application Block的简单示例,请访问在ASP.NET 中使用 ...
spring 项目中集成 Protocol Buffers 示例
http://blog.csdn.net/fangzhangsc2006/article/details/8687388 本文适用于了解spring框架,同时想在spring项目中使用Protocol ...
jsp servlet示例_Servlet和JSP中的文件上传示例
jsp servlet示例使用Servlet和JSP将文件上传到服务器是Java Web应用程序中的常见任务. 在对Servlet或JSP进行编码以处理文件上传请求之前,您需要了解一点有关HTML和 ...

项目README文件的书写示例

前言

项目README文件的书写示例相关推荐

最新文章

热门文章