专栏首页腾讯IVWEB团队的专栏如何写一个通用的README规范

如何写一个通用的README规范

背景

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

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

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


规范的README需要哪些内容

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

image1

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


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

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

每一项都有哪些作用?

  • 项目描述

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

  • 如何运行

i. 开发环境配置。一般是我们需要的一些运行环境配置。

ii. 开发&发布 命令。我们怎么通过命令开启本地开发,以及构建发布。

iii. 代理配置。如果我们的项目在本地开发时需要用到一些代理工具,例如fiddler或whistle等,我们需要列出代理的配置项。最好是直接导出一个代理配置的文件,放在项目下

iv. 发布。如果我们有用到一些发布平台,最好贴上项目的发布模块和发布单,减少我们发布的时间成本。

v. 错误告警及监控。相信我们平常都会对线上的项目部署错误告警和监控日志的服务,方便我们及时排查现网问题,这里我们可以加入项目的一些监控属性ID

vi. 接口API。这里我们需要贴入项目中拉去的后台接口地址以及描述,还有我们的接口负责人,当后台服务异常,可以直接联系到后台同学。

vii . 数据上报。我们在平常项目里都有加入一些数据上报,给产品同学统计业务数据用,这里我们最好阐述下都有哪些数据的上报。如果上报出问题,产品妹子找过来,我们不至于是一脸懵逼。

  • 业务介绍

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

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

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

页面目录

页面描述

页面链接

参数描述

index

首页

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

最后

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

腾讯IVWEB团队的工程化解决方案feflow已经开源:Github主页:https://github.com/feflow/feflow 如果对您的团队或者项目有帮助,请给个Star支持一下哈~

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • [译]通过几个简单的修改,我们减少了React Native app 60%的大小

    App的大小对App的安装率和卸载率都有很大的影响。Google Play有篇很好的文章介绍减少App大小的重要性。

    腾讯IVWEB团队
  • NOW 直播和微信小程序那些事

    微信小程序从发布开始,可谓赚足了眼球,一度引发了开发界“全民学JavaScript”的梗。为了跟上时代步伐,我们NOW直播团队也在发布后第一时间尝鲜,本文就来扒...

    腾讯IVWEB团队
  • 解决 Unexpected lexical declaration in case block 的问题

    Unexpected lexical declaration in case block(no-case-declarations)

    腾讯IVWEB团队
  • 【百度内部分享】如何成为一个优秀的工程师

    一位工程师,如何才能称得上优秀?除了写得一手好Code,什么样的工作态度和方法才是一个优秀工程师的必备? 7月11日,陆奇出席百度内部Engineering L...

    钱塘数据
  • linux下连接windows2003 ppoe 服务器

    1,在CentOS6.3下用 /usr/sbin/pppd  pty "/usr/sbin/pptp publicip --nolaunchpppd" f...

    三杯水Plus
  • 尖端AI学术会议NIPS改名风波:拒绝性别歧视

    在AI和机器学习领域最重要的会议之一:神经信息处理系统大会(NIPS)目前正在考虑更改其名称,部分原因是首字母缩略词的内涵具有性别歧视意味,主要针对英语使用者。...

    AiTechYun
  • 虚拟机中CentOS获取ip

    治电小白菜
  • 马克.贝尼奥夫赢得第八界Crunchie CEO大奖

    在经过旋风般的2014年之后,Salesforce的创始人以及CEO马克奔尼奥夫带着发给他的Crunchie奖项回到了家。贝尼奥夫带领Salesforce走过了...

    臭豆腐
  • 邹建平:智能化大数据平台打造实践

    12月15日,由腾讯云主办的首届“腾讯云+社区开发者大会”在北京举行。本届大会以“新趋势•新技术•新应用”为主题,汇聚了超40位技术专家,共同探索人工智能、大数...

    云加社区技术沙龙
  • Windows服务器重启后登录不上(可能是Recovery模式)

    制作系统镜像参考:https://cloud.tencent.com/document/product/213/4942

    张晗

扫码关注云+社区

领取腾讯云代金券