你的项目需要一个高质量README文档！
来源丨 续渊
juejin.im/post/5cdd09556fb9a0323968b033
先叨叨几句
无论在公司内部，还是在开源社区，我们在接触一个新项目的时候，基本上都会先去看 README 。一份好的README可以使你快速了解甚至上手这个项目，然而一份糟糕的README可能会让你崩溃。
README就像是一本供开发者阅读的 程序简介书 。为了写好这本书，给别人或者自己提高效率，我们需要学习 一些技巧 来编写高可读性的README.
什么是README
README（顾名思义—— "读我" ）是开始一个新项目的时候首先需要阅读的文件。它是关于项目有用信息的集合，同样也是一本手册。
比如：我这个位于 Github上关于 Spring Boot的开源项目，其README就是这个：
一份好README的益处
对于使用你项目的人而言，一份好的REAME可以让其他人迅速了解我们的代码包含的内容、重点、使用方法、技术栈、疑难杂症等。这毫无疑问可以大大减少沟通成本。如果你不想不厌其烦地回答新人的各种问题，那就写一份完整且高可读性的README吧。
而对于我们自身而言，README不仅可以让你在久别重逢该项目后找到往日的熟悉感，它也可以帮助我们总结和规划。我们可以将解决问题的灵感来源记录（如stackoverflow链接），也可以添上完成的功能和即将要实现的特性和优化。从这个角度来说，它像是一本关于项目的日记或者蓝图。
使用何种语言
如果是开源项目，我建议使用英语。毕竟咱们要有一颗international的心。如果是公司内部项目，还是中文“可读性"更强。当然，这个不强求
README应该包含的内容
首先至少应该包括的内容有：
-
标题(Title)
-
介绍(Introduction)
-
技术栈(Technologies)
-
启动(Launch or Setup)
如果考虑得更完善一些还包括：
-
目录(Table of contents)
-
功能特性(Features)
-
代码示例(Code Examples)
-
项目状态（Status）
-
来源(Sources)
-
外部链接(Links)
-
联系(Contact)
-
其它信息
-
...
当然关于内容规范问题仁者见仁智者见智，只要能够达到README应该有的效果，就是好的实践。
README的细节
标题(title)
一个标题应该很清晰地表达这是一个什么项目。通常来说，它会是项目名称。
介绍(introduction)
介绍应该短小精悍，2、3句话就可以讲明白这个项目的目的以及解决的问题。
技术栈(Technologies)
这是程序员最关心的部分之一。它们是这个项目的地基，有了完整且正确的它们才能构建出整个项目，而不是一启动就无数报错。所以我们理应把项目的语言、依赖和对应的版本写下来。比如:
-
Java 8
-
Spring Boot 2.x
-
easyexcel 1.1.0
启动(Launch or Setup)
如何运行也是开发者十分关心的部分。我们不能仅仅只写下一行启动命令，比如 npm run start ，通常来说我们还需要告诉使用者如何安装依赖、如何修改配置甚至初始化数据库。你写得越详细，别人就越少吐槽。
目录(Table of contents)
在篇幅较长、内容较多的情况下，目录提供了一个各部分内容的快捷入口，而不是无止尽地滑滚轮。我们可以用 markdown 提供的便捷语法，创建一个简单的目录。
功能特性(Features)
通过阅读这部分，人们将迅速了解该项目所支持的功能和特性。另外我们也应当将TODO List写上去，以供自己规划项目和他人了解它的未来发展方向。
代码示例(Code Examples)
这对一些工具或者库依赖项目来说是十分重要的。因为通常来说人们更愿意直接复制粘贴来测试他们需要的效果。
项目状态（Status）
项目处于开发阶段还是已经完成，是已经停止维护还是迁移到了新的项目？这值得告诉读者。
来源(Sources)
我们在开发某项功能，或者解决某个bug的过程中，有的时候会查阅一些文档、教程或者从技术论坛寻找现成的解决方案（比如stackoverflow、掘金等）。将其中你认为对自己或他人有价值的一部分记录在案，写下它们的描述和链接。我认为在未来某个时间点，它可能会帮助到你或者别人。
外部链接(Links)
对于公司内部项目而言，可能会有项目管理平台地址（如tapd）、接口文档地址；对于开源项目也可能有对应的完整文档、教程、博客等。
联系(Contact)
主要是记录作者本人或者开发团队的联系方式。
小 结
上述都只是个人看法和建议，只要适合自己的项目，可读性高，达到减少沟通成本的目的就是好的README。
后 记
若有错误或者不当之处，可在本公众号内反馈，一起学习交流！
更多热文在此：
● Spring Boot 系列实战文章合集（源码已开源）
● 程序员写简历时必须注意的技术词汇拼写
● 基于Spring Security OAuth2 的SSO单点登录+JWT权限控制实战
● 从一份配置清单详解Nginx服务器配置
● 如何在Windows下像Mac一样优雅的开发
● Docker容器可视化监控中心搭建
● 利用ELK搭建Docker容器化应用日志中心
● RPC框架实践之：Google gRPC
● 一文详解 Linux系统常用监控工具
更多 务实、能看懂、可复现的 技术文章、资源尽在公众号 CodeSheep ，欢迎扫码订阅，第一时间获取更新 :arrow_down::arrow_down::arrow_down:
正文到此结束
- 本文标签： 开发者 程序员 src MQ Markdown Nginx https UI 时间 example IO 回答 java git 配置 代码 开源 Features 权限控制 spring 质量 安装 GitHub 总结 Security bug 目录 windows 标题 Google 开发 文章 ELK linux tab 数据库 管理 list 项目管理 Spring Security 源码 开源项目 Excel 博客 Spring Boot 测试 tar 数据 Docker http id 服务器
- 版权声明： 本文为互联网转载文章，出处已在文章中说明(部分除外)。如果侵权，请联系本站长删除，谢谢。
- 本文海报： 生成海报一 生成海报二
热门推荐
相关文章
Loading...
![[HBLOG]公众号](http://www.liuhaihua.cn/img/qrcode_gzh.jpg)
