代码仓库规范.md 3.2 KB

代码仓库规范

命名规范

  1. 代码仓库命名统一采用下划线分隔式命名

由于历史原因,代码仓库的命名规则存在大驼峰式、下划线分隔式、短横线分隔式等各种版本,非常不规范。今后的开发,代码仓库命名统一采用短横线 - 分隔式命名

示例:taihe-rpc

  1. 代码仓库的名称要简洁、语义化

代码仓库的命名,尽量采用简洁的英文描述名称,命名要保证语义化及可读性。

README 文件规范

README 文件是项目的上手文档,必须遵循严格的规范性。

一份规范完整的 README 文档要包含一下的要点:

  1. 项目描述

  2. 如何运行

  3. 业务介绍

  4. 项目备注

项目描述

需要说明我们的项目名,项目功能简述,代码仓库地址,以及该项目的第一负责人。谁交接给我们的项目,谁就是该项目的第一负责人。

如何运行

项目如何运行,通常涵盖以下内容:

  • 开发环境配置。一般是我们需要的一些运行环境配置,包括指定硬件或平台要求、语言版本、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 文档不完善甚至是缺失的问题,需要完善。