背景

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

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

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

规范的README需要哪些内容

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

1. 项目描述

2. 如何运行

3. 业务介绍

4. 项目备注

每一项都有哪些作用?

  • 项目描述

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

  • 如何运行

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

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

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

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

      页面目录 页面描述 页面链接 参数描述
      index 首页 https://xxx.com
  • 项目备注 项目中需要告诉其他开发者一些关键信息,比如我们页面打包构建,需要注意哪些问题等等,这些信息虽然不是必须的,但是可以帮助其他开发者降低开发的风险成本。

如何写一个通用的README规范的更多相关文章

  1. 一起学习造轮子(一):从零开始写一个符合Promises/A+规范的promise

    本文是一起学习造轮子系列的第一篇,本篇我们将从零开始写一个符合Promises/A+规范的promise,本系列文章将会选取一些前端比较经典的轮子进行源码分析,并且从零开始逐步实现,本系列将会学习Pr ...

  2. 写一个通用的List集合导出excel的通用方法

    前几天要做一个数据导出Excel 我就打算写一个通用的. 这样一来用的时候也方便,数据主要是通过Orm取的List.这样写一个通用的刚好. public static void ListToExcel ...

  3. 《用Java写一个通用的服务器程序》01 综述

    最近一两年用C++写了好几个基于TCP通信类型程序,都是写一个小型的服务器,监听请求,解析自定义的协议,处理请求,返回结果.每次写新程序时都把老代码拿来,修改一下协议解析部分和业务处理部分,然后就一个 ...

  4. Tsx写一个通用的button组件

    一年又要到年底了,vue3.0都已经出来了,我们也不能一直还停留在过去的js中,是时候学习并且在项目中使用一下Ts了. 如果说jsx是基于js的话,那么tsx就是基于typescript的 废话也不多 ...

  5. 【github】论怎么去写一个高大上的ReadMe

    前言 以前我时常觉得,自己写的ReadMe很单调乏味,但后来仔细研究一下后,发现有很多方式可以让ReadMe在简洁的基础上变得好看些,所以在这里和大家分享,如果大家有更好的想法,也非常欢迎在评论区留言 ...

  6. 一步一步写一个简单通用的makefile(四)--写一个通用的makefile编译android可执行文件

    通常要把我们自己的的代码编译成在android里面编译的可执行文件,我们通常是建一个文件夹 . ├── Android.mk ├── Application.mk ├── convolve.cl ├─ ...

  7. 《用Java写一个通用的服务器程序》02 监听器

    在一个服务器程序中,监听器的作用类似于公司前台,起引导作用,因此监听器花在每个新连接上的时间应该尽可能短,这样才能保证最快响应. 回到编程本身来说: 1. 监听器最好由单独的线程运行 2. 监听器在接 ...

  8. 《用Java写一个通用的服务器程序》03 处理新socket

    在讲监听器时说过处理的新的socket要尽快返回,监听器调用的是ClientFactory的createPhysicalConnection方法,那么就来看这个方法: public boolean c ...

  9. 用C#开发的一个通用的地铁换乘查询工具

    日常生活中,上班下班坐地铁已经是常事,每当我想去某一个远一点的地方,如果有地铁首选就是地铁,因为方便嘛!每次坐地铁,我们都是凭肉眼去得出我们心中最佳的换乘方案,但是,如果对于线路较少的城市来说,这个方 ...

随机推荐

  1. js中表达式 >>> 0 浅析

    zepto源码的Array.prototype.reduce有一行 len = t.length >>> 0 当时就很疑惑,知道 >>是移位,那>>>又 ...

  2. 前端开发之css

    <!--页面中的组成部分通常随便打开一个网页,有文字,图片,视频,表格,音频,表单(注册信息) css 属性/尺寸/边框/背景 1.css的尺寸属性,就是大小width max-width mi ...

  3. scala下划线

    作为函数的参数 一个匿名的函数传递给一个方法或者函数的时候,scala会尽量推断出参数类型.例如一个完整的匿名函数作为参数可以写为 scala> def compute(f: (Double)= ...

  4. Hbase 架构体系

    有2个节点进程,一个是master,另一是regionserver.

  5. Python对elasticsearch的CRUD

    一.官网提供的Elasticsearch的Python接口包 1.github地址:https://github.com/elastic/elasticsearch-dsl-py 2.安装:pip i ...

  6. mybatis逆向工程,实现join多表查询,避免多表相同字段名的陷阱

    ​ mybatis逆向工程,实现join多表查询,避免多表相同字段名的陷阱 ​ 前言:使用 mybatis generator 生成表格对应的pojo.dao.mapper,以及对应的example的 ...

  7. vue自定义组件及传值

    1.使用 Vue.component() 方法注册组件 2.使用 props 属性传递参数 v-for="item in items": 遍历 Vue 实例中定义的名为 items ...

  8. Python——glob模块

    一.作用: 找到匹配上特定格式的所有文件和文件夹,跟windows的文件搜索功能差不多 二.三种匹配符 *代表0个或多个字符 ?代表一个字符 []匹配指定范围内的字符,如[0-9]匹配数 三.应用方法 ...

  9. caffe boost cuda __float128 undefined

    转载:https://blog.csdn.net/thesby/article/details/50512886 编译caffe-master时遇到的问题,__float128未定义,使用到cuda版 ...

  10. 思路 一般创建展示类时候 例如page类 会在网页上新增多个对应字段的隐藏域 用于存储值

    思路 一般创建展示类时候 例如page类 会在网页上新增多个对应字段的隐藏域 用于存储值