1. 首页
  2. 前端进阶

如何写一个通用的 README 规范

背景

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

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

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


规范的README需要哪些内容

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

image1

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


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


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

每一项都有哪些作用?

JS中文网 – 前端进阶资源教程 www.javascriptC.com
一个致力于帮助开发者用代码改变世界为使命的平台,每天都可以在这里找到技术世界的头条内容

  • 项目描述

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

  • 如何运行

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

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

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

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

      页面目录

      页面描述

      页面链接

      参数描述

      index

      首页

      now.qq.com

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

最后

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

链接:https://juejin.im/post/5aaa06e4f265da237b21cf63

看完两件小事

如果你觉得这篇文章对你挺有启发,我想请你帮我两个小忙:

  1. 关注我们的 GitHub 博客,让我们成为长期关系
  2. 把这篇文章分享给你的朋友 / 交流群,让更多的人看到,一起进步,一起成长!
  3. 关注公众号 「画漫画的程序员」,公众号后台回复「资源」 免费领取我精心整理的前端进阶资源教程

JS中文网是中国领先的新一代开发者社区和专业的技术媒体,一个帮助开发者成长的社区,目前已经覆盖和服务了超过 300 万开发者,你每天都可以在这里找到技术世界的头条内容。欢迎热爱技术的你一起加入交流与学习,JS中文网的使命是帮助开发者用代码改变世界

本文著作权归作者所有,如若转载,请注明出处

转载请注明:文章转载自「 Js中文网 · 前端进阶资源教程 」https://www.javascriptc.com

标题:如何写一个通用的 README 规范

链接:https://www.javascriptc.com/2914.html

« 我知道的跨域与安全
VSCode 是怎么运行起来的?»
Flutter 中文教程资源

相关推荐

QR code