如何写一个通用的README规范

背景

我们平常在进行项目开发时，一般都会把代码上传至代码托管平台上方便管理和维护。目前大家使用的托管平台最多的还是Github，国内外还有一些比较知名的代码托管平台，比如Gitlab、BitBucket，码云和码市等。

但我们在多人合作开发下，经常碰到的最头疼的问题是，其他开发者在交接给我们一个项目时只是对项目目前现有的功能简单的描述了下，我们在后续迭代功能时突然发现连最基本的项目如何运行都没有给我们交代，当时心中一万只那个什么马奔腾而过，只能去查看package.json的scripts，自己意会了。

那么问题来了，我们在交接一个项目时，如何保证项目能快速完整地交付给基友，从此过上无忧无虑的生活呢？答案是我们只需要甩给他一份标准规范的README。

• • -

规范的README需要哪些内容

我们通过一张截图一起来看看一份简单的README规范都有哪些内容：

上面的readme规范模板在我们 feflow的 README规范里可以看到

• • -

那么我们一起来探讨下，一份规范完整的README规范都应该有哪些内容呢？

1. 项目描述
2. 如何运行
3. 业务介绍
4. 项目备注

每一项都有哪些作用？

• 项目描述

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

• 如何运行

  1. 开发环境配置。一般是我们需要的一些运行环境配置。
  2. 开发&发布 命令。我们怎么通过命令开启本地开发，以及构建发布。
  3. 代理配置。如果我们的项目在本地开发时需要用到一些代理工具，例如fiddler或whistle等，我们需要列出代理的配置项。最好是直接导出一个代理配置的文件，放在项目下
  4. 发布。如果我们有用到一些发布平台，最好贴上项目的发布模块和发布单，减少我们发布的时间成本。
  5. 错误告警及监控。相信我们平常都会对线上的项目部署错误告警和监控日志的服务，方便我们及时排查现网问题，这里我们可以加入项目的一些监控属性ID
  6. 接口API。这里我们需要贴入项目中拉去的后台接口地址以及描述，还有我们的接口负责人，当后台服务异常，可以直接联系到后台同学。
  7. 数据上报。我们在平常项目里都有加入一些数据上报，给产品同学统计业务数据用，这里我们最好阐述下都有哪些数据的上报。如果上报出问题，产品妹子找过来，我们不至于是一脸懵逼。

• 业务介绍

  对于前端来说，我们一个项目可能不止一个页面，那么我们需要给出以下信息:

  1. 业务入口地址及渠道链接 即我们整个项目的入口页面，或者比较重要的页面地址。一般入口页面，我们可能会在多个渠道进行投放，那么需要列出所有的渠道链接

  2. 各页面及描述 列出我们项目内的所有页面信息，比如下面这样：

     页面目录	页面描述	页面链接	参数描述
     index	首页	https://now.qq.com	无

• 项目备注 项目中需要告诉其他开发者一些关键信息，比如我们页面打包构建，需要注意哪些问题等等，这些信息虽然不是必须的，但是可以帮助其他开发者降低开发的风险成本。

最后

上面是我们一个规范的README所需的一些信息和内容，加粗内容是我认为README里的一些必需信息，大家也可以在此基础上针对自己项目实际的开发场景来扩展一些规范信息。

腾讯IVWEB团队的工程化解决方案feflow已经开源：Github主页： https://github.com/feflow/feflow

如果对您的团队或者项目有帮助，请给个Star支持一下哈～