作为一个程序员, 为自己的项目或仓库撰写README是必不可免的工作. 一个好的规范的README文件可以让其他人快速准确地理解你的仓库代码, 快速地安装并使用, 并在必要的时候知道如何与你合作, 对开源项目的传播有极大的帮助.
那么该如何撰写一份规范简介的README文件呢? 一个标准的README文件又该具备哪些部分? 如果你同样有这些疑问, 请仔细阅读本文, 我相信会给你很大的帮助.
README文件必须在别人能访问到项目或仓库之前准备好. 在新建项目时就为项目同时新建好README文件是一个良好的开发习惯, 它应该是所有项目仓库提交的第一个文件.
通常情况下放在项目的根目录底下, 因为这是别人第一次访问你的项目或仓库时最先进入的地方. GitHub和GitLab等平台会默认自动寻找你项目中的README文件, 并将其展示在你的项目目录底部.
虽然从理论上来说, README文件可以是任何能显示txt的文件格式, 但是最常用的还是Markdown格式.
我们先来看一个比较简单的README文件, 这是一个最简单的模板. 由于每个项目的不同, 你不一定要遵循该模板, 在本文后面的部分我们会对模板中必要的部分进行讲解和讨论.
README.md 模板
Foobar is a Python library for dealing with word pluralization.
Use the package manager pip to install foobar.
import foobar
# returns 'words'
foobar.pluralize('word')
# returns 'geese'
foobar.pluralize('goose')
# returns 'phenomenon'
foobar.singularize('phenomena')
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Please make sure to update tests as appropriate.
MIT
由于每一个项目都是不同的, 所以很难给出一个标准的README的格式, 你必须根据自己的项目来对模板进行调整. 虽然通常来讲README不会非常冗长, 但是当你发现你写的README长度过长时, 应当考虑其他格式的文档, 而不是去删减README中的内容. 因为更详细的README一定好过太短的, 尽量确保他人需要知道的信息都包含在README中.
下面列举了一些README中非常必要的部分供大家参考.
为你的项目或仓库取一个好名字是必不可少的. 一个好的名字必须拥有自解释性, 即他人看到这个名字就能明白该仓库的核心功能, 无需更多的解释.
让人们知道你的项目具体能做什么. 提供上下文并添加到访问者可能不熟悉的任何参考的链接. 也可以在这里添加功能列表或背景子部分. 如果你的项目有其他相似的或可替换的项目, 这是一个列出与其他项目差异化因素的好地方.
你可能在某些README文件中看到过一些徽章, 用来表示下载次数, 版本或者其他信息. 如果你没有见过, 那么我们这里所说的徽章就是指下面这个小东西:
Static Badge如果你想在自己的README中添加这个, 那么Shields.io是一个不错的选择, 另外网络上还有很多其他的网站也都可用生成它们.
为了让访客们更方便理解代码的执行效果, 在README中添加一些截图, 动图或者视频是非常好的选择. 有许多小工具可用帮助你, 例如ttygif
安装指导是README中 不可省略的. 通常需要列举出在不同环境中的详细安装过程. 请考虑访客是一个新手的可能, 尽可能地展示安装过程, 具体的步骤有助于消除歧义.
如果你的项目只能在特定的依赖中运行, 那么也需要在这里指出. 如果依赖非常复杂, 需要在README中添加额外的Requirements小节来进行解释.
给出一些小的使用案例, 并尽可能列出预期的输出. 如果可能的话, 给出复杂示例的跳转链接, 如果这些示例太长而无法被合理地包含在README中.
告诉访问者如何能够联系你, 这样它们就可以向你寻求帮助或者为项目提供一些贡献.
如果你未来有更新的计划或者TODO List, 也可以在README中列举出来.
说明你是否愿意接受捐款, 以及接受捐款的条件是什么.
对于想要更改项目的人来说, 有一些关于如何开始的文档是很有帮助的. 也许他们需要运行一个脚本, 或者需要设置一些环境变量. 明确这些步骤. 这些指导对你未来的自己也很有用.
你还可以记录命令以检查代码或运行测试. 这些步骤有助于确保高质量的代码, 并减少更改无意中破坏某些东西的可能性. 如果需要外部设置, 例如在浏览器中启动Selenium服务器进行测试, 那么提供运行测试的说明尤其有用.
向那些项目的贡献者或者为你提供过帮助的人表示真诚的感谢, 可以在此处引用他们的博客主页或者GitHub主页.
对于开源项目来说, 需要附加License. 如果你不知道怎么选择一个合适你的License, 那么这个网站会帮助你: Choose an open source license
如果你已经没有精力或者计划继续维护这个项目, 请在README的顶部注明项目的开发已经完全停止. 如果你希望人们自愿作为维护者来介入来让项目继续下去也可以在这个小节发出请求.
你可以在README中添加一个跳转到Changelog的链接, 详细记录项目各个版本之间的区别以及注意事项.
虽然README文件对于项目来说是必不可少的, 但是有很多时候也是不够用的. 有很多其他形式的文件将会帮助你更好地解释并推广你的开源项目.