README

项目 README 很重要

困扰很多新手的问题，大部分情况下都是项目本身的问题，最基本的指引文档都没有，确实让人抓狂。

抛开业务层面不谈，只说纯代码层面的内容，业务上的内容需要通过阅读需求文档、查看原型、切身使用系统来慢慢消化。

理想情况下，一个新成员加入项目时，应该可以通过阅读一份文档就能将项目启动起来，并且可以本地调试。这本来应该是再正常不过的了，但是很遗憾，现实中有很多项目根本没有这样的文档，或者文档有缺漏。

这个文档你到 GitHub 上随便找一个开源项目，照着 README 去写就好了，其实就是一份使用指南。当你写文档时应该站在一个从未使用过项目的人的视角出发，最终目的就是指引新成员独立启动项目，格式不格式的不重要。

这个文档可能包括如下这些内容，根据项目的具体情况还可以做调整：

1. 仓库地址，每个分支的作用；

2. 是否有私有 Maven 仓库，应该如何配置；（假设有人之前用 Gradle ，可能就不了解 Maven，反之亦然，不要想当然的一个Java开发者必然已经了解 Maven）

3. 如果有多环境的话，每个环境的使用场景，如何指定环境，通过 VM 参数还是其他的；

4. 需不需要指定额外的参数，例如前面那位同学的项目，好多参数是配置在环境变量中的，这要是不说明，光看代码会很累的；

5. 如果是微服务的话，那多个服务的配置更要写清楚；

6. 如何调试接口，有的项目有权限校验之类的全局控制，也要写清楚请求头、额外参数什么的，尤其是那种很个性化的参数；

7. 如何打包、发布测试环境等等；

8. 如何查看测试环境、线上环境日志，尤其是没有统一的在线日志系统的；

作为项目成员，一定要整理一份这样的文档，方便他人，也是方便自己。否则哪天来个新人缠着你问，你不要嫌烦就可以。

退一万步讲，就算项目确实很简单，没有什么文档，那新成员加入也要给人家交代清楚。

别不好意思，该问就问

第一步：有没有文档，没有吗？那能不能给我写一份文档。
第二步：不好写，浪费时间？好，能不能帮我讲一下架构和项目配置。

所以刚接手项目的同学，对于项目本身的问题，该问就问。应该感到羞愧的是项目组的其他成员，文档没写清楚，项目配置乱七八糟，就这，还好意思嫌弃别人吗？

引用:mp.weixin.qq.com/s/9-hPH_mrCHYkddq...

本作品采用《CC 协议》，转载必须注明作者和本文链接