如何为你的 GitHub 项目编写一份好的 readme 文件

我第一次接触 GitHub 时，根本不知道它是什么，也不知道它能做什么。我私下里说，我创建这个账户是因为有人告诉我，每个开发人员都应该有一个账户，用于发布他们的代码。

作为一名初学者，很长一段时间我都没有用我的账户做任何事情。但后来，由于我对技术的热情，我开始关注其他开发人员并在 GitHub 上查看他们的工作。我注意到他们有一个共同点：他们都有很酷的项目，并为开源做出了贡献，但他们的项目也有详细的 README 文件 .

因此，我对 README 的兴趣与日俱增，我决定尝试在我的项目中添加一个。我不会撒谎——我匆忙地做了这件事，根本不知道应该怎么做。老实说，它一点也不好。点击 此处 .

这种情况持续了一段时间。但通过实践和不断学习，我能够改写一些更好的文档，比如 这个 ，这提高了项目的参与度，并帮助其他开发人员参与进来。

还需要注意的是，好的 README 将帮助你在将其工作发布在 GitHub 上的众多开发人员中脱颖而出。

在本文中，我们将进一步了解什么是 README 文件以及如何编写 README 文件。首先，让我们了解一下 README 文件的含义。

什么是 README 文件？

简单来说，我们可以将 README 文件描述为一种指南，为用户提供您所从事的项目的详细描述。

它也可以被描述为包含如何使用项目的指南的文档。通常它会包含如何安装和运行项目的说明。

作为开发人员，你必须知道如何通过编写 README 来记录你的项目，因为：

• 这是人们遇到您的项目时看到的第一个文件，因此它应该相当简短但详细。
• 这将使您的项目从众多项目中脱颖而出。同时确保您的项目也很好。
• 它将帮助您专注于项目需要交付的内容以及如何交付。
• 它会提高你的写作技巧，正如弗里德里希·尼采所说：

一个好的作家，不仅拥有自己的精神，而且拥有朋友的精神。

在开展项目时，请记住，您需要其他开发人员了解您的代码及其功能。因此，附上一份额外的指南将非常有帮助。

例如，我之前分享的 第一个项目 没有很好的 README。尽管这个项目很棒，但对于初学者来说，当他们克隆我的仓库时，很难准确理解预期的内容。谁知道它甚至可能是编码病毒。

对于 GitHub 上这样的项目，无论它多么出色，如果没有良好的 README，其他开发人员都不会愿意去研究它并尝试弄清楚它。

现在，看一下这个 项目 。在这里，您可以了解该项目的作用，它包含的内容，以及如果您需要使用或想要为该项目做出贡献，如何开始。

您会发现，一份写得好的 README 有多么强大，以及它如何改变您的项目。

那么，让我们开始为您编写一个吧。

如何撰写优秀的 README – 分步指南

需要注意的一件非常重要的事情是，没有一种正确的方法来构建一个好的 README。但有一种非常错误的方法，那就是根本不包含 README。

通过研究和学习各种 README 文件，我肯定找到了一些最佳实践。这就是我要分享的内容。正如我通常告诉自己的那样：

每天都是学习日。

因此，随着您的职业生涯不断进步，您将对如何制作一份好的 README 以及如何改进它形成自己的想法。也许您甚至会想出自己独特的指南。

在我们开始之前，还需要注意的是，当你编写项目的自述文件时，它应该能够回答 是什么 , 为什么 和 如何 的问题。

以下是一些可以帮到你的指导性问题：

• 你的动机是什么？
• 你为什么要建立这个项目？
• 它解决了什么问题？
• 你学到了什么？
• 什么让你的项目脱颖而出？
  如果您的项目有很多功能，请考虑添加“功能”部分并在此处列出它们。

README 中应包含哪些内容

1. 项目名称

这是项目的名称。它用一句话描述整个项目，并帮助人们了解 项目的主要目标和目的是 什么

2. 项目描述

这是项目的一个重要组成部分，但许多新开发人员经常忽视它。

您的描述是项目的一个极其重要的方面。精心编写的描述可以让您向其他开发人员以及潜在雇主展示您的工作。

README 描述的质量通常可以区分一个好的项目和一个坏的项目。好的 README 会利用机会来解释和展示：

• 你的应用程序的作用
• 为什么你使用你所使用的技术，
• 您所面临的一些挑战以及您希望在未来实现的功能。

3. 目录（可选）

如果您的 README 很长，您可能需要添加目录，以便用户轻松导航到不同部分。这将使读者更轻松地浏览项目。

4.如何安装并运行项目

如果您正在开发一个用户需要在“POS”之类的机器上本地安装或运行的项目，那么您应该包括安装项目所需的步骤以及所需的依赖项（如果有）。

提供如何设置和运行开发环境的逐步描述。

5. 如何使用本项目

提供说明和示例，以便用户/贡献者可以使用该项目。这样，如果他们遇到问题，他们就可以轻松解决问题——他们总有一个地方可以参考预期的内容。

您还可以利用视觉辅助工具，包括屏幕截图等材料来展示正在运行的项目的示例以及项目中使用的结构和设计原则。

此外，如果您的项目需要密码或用户名等身份验证，这是一个包含凭据的好部分。

6. 包括致谢

如果您以团队或组织的身份参与该项目，请列出您的合作者/团队成员。您还应该包括他们的 GitHub 个人资料和社交媒体的链接。

此外，如果您遵循教程或引用了可能有助于用户构建特定项目的某些材料，也请在此处包含指向这些材料的链接。

这只是表达感激之情的一种方式，同时也可以帮助其他人获得该项目的第一手副本。

7. 添加许可证

对于大多数 README 文件来说，这通常被视为最后一部分。它让其他开发人员知道他们可以对您的项目做什么，不能做什么。

根据您从事的项目类型，我们提供不同类型的许可证。您选择的许可证将决定您的项目将获得的贡献。

最常见的是 GPL 许可证，它允许其他人修改您的代码并将其用于商业目的。如果您需要帮助选择许可证，请查看此链接： https://choosealicense.com/

到目前为止，我们已经介绍了一份好的 README 的最低要求。但您可能还想考虑添加以下部分，使其更引人注目、更具互动性。

其他自述文件部分

8.徽章

徽章不是必需的，但使用它们是让其他开发人员知道您知道自己在做什么的简单方法。

此部分还有助于链接到重要工具，并显示有关项目的一些简单统计数据，如分叉数量、贡献者、未解决的问题等...

下面是我的一个项目的屏幕截图，展示了如何使用徽章：

此部分的优点在于它能够自动更新。

不知道从哪里获得它们？查看 shields.io 。他们有大量徽章可帮助您入门。您现在可能不明白它们代表什么，但随着时间的推移，您会明白的。

9. 如何为项目做贡献

如果您正在开发一个需要其他开发人员参与的开源项目，这将非常有用。您需要添加指南，让他们知道如何为您的项目做出贡献。

另外，确保你为开源项目选择的许可证正确，以避免将来发生冲突也很重要。添加贡献指南将发挥重要作用。

一些最常见的准则包括 贡献者契约 和 贡献指南 。这些文档将为你在为项目制定规则时提供所需的帮助。

10. 包括测试

加倍努力，为您的应用程序编写测试。然后提供代码示例以及如何运行它们。

这将有助于表明你确信你的项目将顺利进行，这也会让其他人对它充满信心

额外积分

编写 README 时还需注意以下几点：

• 保持最新 - 确保您的文件始终保持最新是一种很好的做法。如果有更改，请确保在必要时更新文件。
• 选择一种语言 - 我们都来自不同的地区，我们都说不同的语言。但这并不意味着你需要将代码翻译成当地语言。用英语编写 README 是可行的，因为英语是一种全球通用的语言。如果你的目标受众不熟悉英语，你可能需要在这里使用翻译工具。

包起来

以上就是您需要的一切，可以改进您的 README 文件，甚至可以帮助您开始编写第一个 README 文件。

此时，我相信您可以为您的下一个项目甚至现有项目添加一个交互式信息指南，让您的项目脱颖而出。

您还可以使用许多工具来自动生成项目的 README，但在转向自动化之前，自己尝试一下总是一个好习惯。如果您想查看它们，它们包括：

• 制作 README
• 自述文件生成器
• 自述

如果您读到这里，我真的很感激。如果您喜欢这篇文章并发现它有用，请分享它，这样您就可以帮助其他开发人员改进他们的项目。

我很想看看您新制作的 README 文件。请务必通过以下任何链接与我分享链接：

与我联系 Twitter | YouTube | LinkedIn | GitHub

请分享您宝贵的意见，我很感谢您的诚实反馈！

享受编码