你的git项目须要一个高质量的README

不管在公司内部，仍是在开源社区，咱们在接触一个新项目的时候，基本上都会先去看README.一份好的README可使你快速了解甚至上手这个项目，然而一份糟糕的README可能会让你崩溃。

README就像是一本供开发者阅读的程序简介书。为了写好这本书，给别人或者本身提升效率，咱们须要学习一些技巧来编写高可读性的README.

什么是README

README（顾名思义——"读我"）是开始一个新项目的时候首先须要阅读的文件。它是关于项目有用信息的集合，一样也是一本手册。

egg的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应该有的效果，就是好的实践。

标题(title)

一个标题应该很清晰地表达这是一个什么项目。一般来讲，它会是项目名称。

介绍(introduction)

介绍应该短小精悍，二、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。

文章灵感来源：www.flynerd.pl/2018/06/jak…