由于历史原因,代码仓库的命名规则存在大驼峰式、下划线分隔式、短横线分隔式等各种版本,非常不规范。今后的开发,代码仓库命名统一采用短横线 -
分隔式命名。
示例:taihe-rpc
代码仓库的命名,尽量采用简洁的英文描述名称,命名要保证语义化及可读性。
README 文件是项目的上手文档,必须遵循严格的规范性。
一份规范完整的 README 文档要包含一下的要点:
项目描述
如何运行
业务介绍
项目备注
需要说明我们的项目名,项目功能简述,代码仓库地址,以及该项目的第一负责人。谁交接给我们的项目,谁就是该项目的第一负责人。
项目如何运行,通常涵盖以下内容:
开发环境配置。一般是我们需要的一些运行环境配置,包括指定硬件或平台要求、语言版本、SDK 版本等。
开发&发布命令。提供完整的、验证过的脚本命令,描述如何开启本地开发,以及构建打包。
代理配置。如果项目在本地开发时需要用到一些代理工具,例如fiddler或whistle等,我们需要列出代理的配置项。最好是直接导出一个代理配置的文件,放在项目下。
发布。描述项目发布的流程和相关脚本,如果是通过 Jenkins 自动构建,需要贴出具体的 Jenkins 任务地址。
说明项目的主要业务内容,同时介绍项目结构。
项目结构要写清楚目录分配和作用,配置文件、路由文件等需要明确指出。
项目结构举例:
.
├── README.md
├── config // 各个小程序各种环境配置文件
├── package.json
├── project.config.json // 小程序项目配置文件,默认加载
└── src
├── app.js // 小程序主入口文件,默认加载
├── app.less // 全局样式,默认加载
├── assets // 资源文件
├── components // 组件库
├── config // 项目相关配置文件,与环境配置文件区分使用
│ ├── dev.js
│ ├── index.js
│ └── prod.js // 切换文件中qa和prod配置,打包生成对应的环境
├── index.html // h5项目才能使用的
├── layouts // 布局文件
├── pages // 项目页面
├── server // 接口和服务相关
├── store // 全局状态管理
├── subpages // 项目分包页面
└── utils // 工具库
项目中需要告诉其他开发者一些关键信息,比如我们页面打包构建,需要注意哪些问题等等,这些信息虽然不是必须的,但是可以帮助其他开发者降低开发的风险成本。
在开发构建打包过程中,遇到环境配置等问题,解决后也可以更新在这部分文档。
由于历史原因,前后端部分项目存在 README 文档不完善甚至是缺失的问题,需要完善。