1. 从写好README开始
一个好的README给人以项目概览,可以使新人快速上手项目,并降低沟通成本,建议包括:
-
项目简介
-
一两句话描述该项目实现的业务功能
-
-
技术选型
-
项目的技术栈,包括语言,框架,中间件等
-
-
本地构建
-
列出本地开发过程中所用到的工具命令
-
-
领域模型
-
核心的领域概念,针对于当前系统所在的领域
-
-
测试策略
-
自动化测试如何分类
-
-
技术架构
-
技术架构图
-
-
部署架构
-
部署架构图
-
-
外部依赖
-
项目运行时所以来的外部集成方
-
-
环境信息
-
各个环境的访问方式,数据库连接
-
-
编码实践
-
统一的编码实践,比如异常处理原则,分页封装等
-
-
FAQ
-
开发过程中常见问题的解答
-
注意保持README的持续更新,一些重要的架构决定可以通过示例代码的形式记录在代码块当中,新开发者可以通过直接阅读这些示例代码快速了解项目的通用实践方式以及架构选择