一份好的README可以给人以项目全景概览,可以使新人快速上手项目,可以降低沟通成本。同时,README应该简明扼要,条理清晰,建议包含以下方面:

项目简介:用一两句话简单描述该项目所实现的业务功能;

技术选型:列出项目的技术栈,包括语言、框架和中间件等;

本地构建:列出本地开发过程中所用到的工具命令;

领域模型: 核心的领域概念,比如对于示例电商系统来说有Order、Product等;

测试策略:自动化测试如何分类,哪些必须写测试,哪些没有必要写测试;

技术架构:技术架构图;

部署架构:部署架构图;

外部依赖:项目运行时所依赖的外部集成方,比如订单系统会依赖于会员系统;

环境信息:各个环境的访问方式,数据库连接等;

编码实践:统一的编码实践,比如异常处理原则、分页封装等;

FAQ:开发过程中常见问题的解答。

需要注意的是,README中的信息可能随着项目的演进而改变(比如引入了新的技术栈或者加入了新的领域模型),因此也是需要持续更新的。虽然我们知道,软件文档的一个痛点便是无法与项目实际进展保持同步,但是就README这点信息来讲,还是建议开发者们不要吝啬那一点点敲键盘的时间。

此外,除了保持README的持续更新,一些重要的架构决定可以通过示例代码的形式记录在代码库中,新开发者可以通过直接阅读这些示例代码快速了解项目的通用实践方式以及架构选择

Last modification:November 9th, 2020 at 04:14 pm
如果觉得这篇技术文章对你有用,请随意赞赏