如何写一个通用的README规范

发表于 | 分类于 | 阅读次数
undefined

在刚开始学前端的时候，udacity有一门教如何写README的课程，那时候吧懵懂无知，就稍微学学便过去了。其实也没留下什么具体印象，有的只是磨炼了一下写markdown的手法。然后慢慢地开始走进了频繁使用github管理，有大量频繁的项目。不过感觉在公司中，大家在代码规范这一块尚且处于一个起步阶段，很多内容大家都是没有进行规范化管理，emm感觉长久而言，对自己不是一件好事吧。
so,今天在掘金上看到鹅厂的老大哥发布了如何写一个通用的README规范毫无疑问必须进行膜拜一把，也算是摘录在自己的blog中呗。

那么一份规范的README需要有什么内容呢？

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

每一项都有哪些作用？

项目描述

需要说明我们的项目名，项目功能简述，代码仓库地址。 这一块感觉像一个更像总起摘要的东西。

如何运行

开发环境配置

一般是我们需要的一些运行环境配置。根据经验主要填上node版本/框架版本(往往有存在定版存在)。

开发&发布命令

这里应该需要分两块进行描述。本地开发的命令，以及构建发布的命令。

  1. 开发命令。这个如果是你自己起的项目，那么可能真的没有太大意义。但是对于一个刚接手项目的小伙子，他便十分需要这块的描述。想当初我刚接手的项目，真的你别说虽有脚手架存在，但是一些依赖的不同等原因。你要把一个项目跑起来真的有莫名其妙的坑存在。例如我新接手的项目，公司使用了sqlite3-online模块，这个模块npm i后居然要修改文件名把sqlite3-online修改成sqlite3才能跑起来。=。=懵懂无知的我，一直根据报错提示以为是我本地环境的问题，最后我导师提了一句我才知道。。。。这明显是给后人挖了个巨大的坑哇…还有一些项目因为没有README的存在，所以到现在我还不知道怎么把它在本地环境跑起来，为什么跑起来会报错。而唯一知道的人已经离职了=。=
  2. 构建发布的命令。这个命令不用我说，当你的代码被部署人员拿出去部署的时候你就会知道了。因为别人没有学过你这个玩意，你乍一看这不是多简单的事吗？然而实际上，你需要手把手教导，细致到他只需要无脑复制你给他的命令，他就能把项目启动起来。无需任何过多知识含量。这同样意味着，你的代码对于端口/有必要弄成全局配置的东西，请统统全局配出来，不要让你的部署小哥去看你的代码。而且这些内容也必须把注释写得清清楚楚。被坑完你就懂了233

  3. 代理配置

    如果我们的项目在本地开发时需要用到一些代理工具，例如fiddler或whistle等，我们需要列出代理的配置项。最好是直接导出一个代理配置的文件，放在项目下。emm,没有做过不清楚，嘿嘿。

发布

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

错误告警及监控

相信我们平常都会对线上的项目部署错误告警和监控日志的服务，方便我们及时排查现网问题，这里我们可以加入项目的一些监控属性ID。这个我没有太理解监控属性ID的意思，emm而且一般而言，部署人员发现哪里跑不通了都直接打你电话问你了，其实吧。写在文档里，可能更多是一个规范化的做法？不过也能算是不给后人挖坑的做法。
另外对于后台服务异常，我更倾向于建议在log日志中将每一次请求的发包回包都进行打印。不为什么，就因为当后台出错，部署人员打到电话给你的时候，你可以让他直接进log日志，“你看，我包发出去了对吧？看到没，包没回包，回包格式不对。你去怼后台吧”。因为这种情况我也是被坑了多次了，后台服务挂了，导致前端不正常，然后你负责第一个定位问题。如果一开始没有进行这么方便的操作，往往你都需要和部署人员说“部署哥哥，进一下我的代码加一点打印语句吧。”然后捣鼓个老半天才终于发现不是自己的问题。
不过吧，这里可能会导致日志文件的增加。因为像我写过的项目，一分钟可能就有一个请求，至少两个打印语句了。那样增量还是挺大的不是=。= 但是这个小技巧真的提高定位bug的速度，再也不用担心明明自己没出问题，却在帮忙定位人家的问题。

接口api

这里我们需要贴入项目中拉去的后台接口地址以及描述，还有我们的接口负责人，当后台服务异常，可以直接联系到后台同学。这里一直都有写，不过鹅肠老铁没列出规范的格式方法呀。
这里有时候列出所有api的确会很繁琐，有一些简单的我也觉得不是特别有紧迫。但是对与和后台交互的那部分！！请务必列出来！！因为你开发完了，以后如果遇到重构什么的，这个接口不是你自己写的，别人或者自己改起来真的超级麻烦。
想当初我就是通过自己模拟着前端的请求，再结合的代码，逐步把旧代码里面和后台的接口理了出来。。。。这个艰辛的日子呐。

数据上报。

我们在平常项目里都有加入一些数据上报，给产品同学统计业务数据用，这里我们最好阐述下都有哪些数据的上报。如果上报出问题，产品妹子找过来，我们不至于是一脸懵逼。
这一块可能主要在于我没有接触这种类型的吧。我暂时开发过的内容都是属于辅助后台的应用页。

业务介绍

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

  1. 业务入口及渠道链接即我们整个项目的入口页面，或者比较重要的页面地址。一般入口页面，我们可能会在多个渠道进行投放，那么需要列出所有的渠道链接
  2. 各页面及描述列出我们项目内的所有页面信息，比如下面这样：
页面目录 页面描述 页面链接 参数描述
index 首页 https://now.qq.com 无
  1. 项目中需要告诉其他开发者一些关键信息，比如我们页面打包构建，需要注意哪些问题等等，这些信息虽然不是必须的，但是可以帮助其他开发者降低开发的风险成本。有关这块我比较倾向于写在和构建命令一起。当然如果有别的细节也可以在这里详细说出，例如代码哪里的修改会牵扯到另一个地方的代码，修改时候要注意之类的=。=（感觉如果写出这种注释是不是就意味着本来这个结构的代码就很糟糕了）

最后可以写一些todoList吧

有时候业务比较忙，可能这套代码还有一些你觉得不够尽善尽美的地方完全可以再这个位置记录下来。一来，以后有时间你可以倒推回来修改。二来，给接受的新人一个修改的方向。（你告诉他这个地方有需要修改，他才敢改呀。不然。。。谁敢乱动哦）

还有一个可以记录的就是..一些不太正常的操作，你觉得有必要提出以下警醒后人的操作。