如何给你的git项目编写一份高质量的README?

栏目: 编程工具 · 发布时间: 4年前

内容简介:无论在公司内部,还是在开源社区,我们在接触一个新项目的时候,基本上都会先去看README.一份好的README可以使你快速了解甚至上手这个项目,然而一份糟糕的README可能会让你崩溃。README就像是一本供开发者阅读的程序简介书。为了写好这本书,给别人或者自己提高效率,我们需要学习一些技巧来编写高可读性的README.README(顾名思义——"读我")是开始一个新项目的时候首先需要阅读的文件。它是关于项目有用信息的集合,同样也是一本手册。

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

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

什么是README

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

如何给你的git项目编写一份高质量的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)

介绍应该短小精悍,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)、接口文档地址; 对于开源项目也可能有对应的完整文档、教程、博客等。


以上所述就是小编给大家介绍的《如何给你的git项目编写一份高质量的README?》,希望对大家有所帮助,如果大家有任何疑问请给我留言,小编会及时回复大家的。在此也非常感谢大家对 码农网 的支持!

查看所有标签

猜你喜欢:

本站部分资源来源于网络,本站转载出于传递更多信息之目的,版权归原作者或者来源机构所有,如转载稿涉及版权问题,请联系我们

算法艺术与信息学竞赛

算法艺术与信息学竞赛

刘汝佳 / 清华大学出版社 / 2004-1 / 45.00元

《算法艺术与信息学竞赛》较为系统和全面地介绍了算法学最基本的知识。这些知识和技巧既是高等院校“算法与数据结构”课程的主要内容,也是国际青少年信息学奥林匹克(IOI)竞赛和ACM/ICPC国际大学生程序设计竞赛中所需要的。书中分析了相当数量的问题。 本书共3章。第1章介绍算法与数据结构;第2章介绍数学知识和方法;第3章介绍计算机几何。全书内容丰富,分析透彻,启发性强,既适合读者自学,也适合于课......一起来看看 《算法艺术与信息学竞赛》 这本书的介绍吧!

在线进制转换器
在线进制转换器

各进制数互转换器

RGB HSV 转换
RGB HSV 转换

RGB HSV 互转工具