规范的README
规范的README
前言：
Github上浏览开源项目时通常项目根目录都有一个字说明文件README.md，该文件可以帮助开发或使用者快速的熟悉和使用这个项目。为项目写出规范的README文件是有必要的。
1 README的作用
README是项目的自述文件，通常它 README.md 是项目的第一个入口文件，而不是急着看代码。阅读它能使得开发或使用者快速熟悉和使用该项目。
2 README应该有哪些内容
README应该告诉阅读者如何使用你的模块或工程，如果安装和使用它。标准的方式编写README将使得阅读理解它更轻松，维护更加方便。
在Github上有一个关于README的开源项目 RichardLitt/standard-readme ，可以访问它，本篇文章也是基于此规范进行讨论。
以下是一个好的README应该具有的内容。
3 标题(Title)
标题为必填项，一般与仓库名、文件夹名或包管理器名同名。标题允许写副标题，副标题加括号斜体表示。
1 | # 主标题 _(副标题)_ |
4 横幅(banner)
可选项，横幅用于丰富显示效果，提供链接到本地存储库。
要求：
- 不能有自己的标题；
- 必选链接到当前存储库中的本地映像；
- 必选直接出现在标题后面；
5 徽章(badges)
可选项，徽章用于丰富显示效果，提供快速跳转链接。
6 简述(Short description)
必选项，对仓库进行简单概述，方便阅读者快速了解项目。
要求：
- 不能有自己的标题；
- 必选少于120个字符；
- 不能以
>开始；- 一定是在它自己的行上；
- 必选符合包管理器的
描述字段；- 必选符合Github的描述（如果在GitHub上）；
7 详细描述(Long description)
可选项，对仓库进行详细描述。
要求：
- 不能有自己的标题；
- 如果任何文件夹、存储库或包管理器名称不匹配，则必选在这里说明原因；
建议：
- 如果内容较多，应考虑将部分内容放到到背景部分；
- 建议描述构建仓库的主要原因；
- 大致的描述模块信息；
8 目录(Table of contents)
小于100行的README为可选项，大于100行的README为必选项。
要求：
- 必选链接到文件中的所有Markdown部分；
- 必选从下一节开始，不要包含标题或目录标题；
- 必选至少有一个深度，也即捕获所有的
##二级标题；
建议：
- 可以捕获第三个和第四个深度标题。如果是长目录，这些是可选的；
9 安全(Security)
可选项，如果有强调安全问题则可描述。
10 背景(Background)
可选项。
要求：
- 包含动机；
- 包含抽象依赖关系；
- 包含只是来源；
11 安装(Install)
必选项，说明安装和使用的方法。
要求：
- 说明如何安装和使用仓库；
- 若有其他环境依赖，说明依赖哪些环境及说明安装环境的方法；
12 用法(Usage)
必选项，说明使用仓库的方法。
13 API
可选项，API接口和对象。
要求：
- 描述签名、返回类型、回调和事件；
- 指明不容易理解的类型；
- 描述注意事项；
- 如果使用外部API生成器，应该链接到外部API的描述文件。
14 维护者(Maintainers)
可选项，说明仓库的开发维护人员。
要求：
- 列出参与该仓库维护的人员，给出他们的联系方式，Github一般给链接或邮件；
建议：
- 必选是重要的开发和维护人员，而不是列出所有有访问权限的人。
15 致谢(Thanks)
可选项，说明对该仓库构建提供过帮助的人或事。
要求：
- 说明对项目的开发有重要帮助的任何人或任何事情；
- 标明公共链接，如果有的话；
16 贡献(Contributing)
必选项，说明用户可参与仓库的权限和方法。
要求：
- 说明用户可以提问的地方；
- 说明是否可接受PR；
- 列出所有贡献的要求，例如在提交时要有签名；
建议：
- 更详细的描述可以链接到 如何贡献.md 文件；
- 链接到 如何贡献规范.md 文件，对贡献的规范操作进行更详细的介绍；
17 许可证(License)
必须项，关于许可证的描述。
要求：
- 声明许可证全名或标识符，提供链接到许可证文件。
- 声明许可证的持有人；
- 放在文件末；
18 模板示例
以下是可套用的README.md规范模板。
1 | # 标题(Title) |
本博客所有文章除特别声明外，均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来源 OnlyCalm's Blog！
相关推荐
2021-07-24
Shields使用教程
Shields使用教程前言： Shields是制作徽章的工具，在各大代码托管平台上被广泛使用，掌握它将利于我们编写出更加漂亮规范的README说明。 1 Shields Shields 是目前主流的徽章制作工具，简介快速生成徽章，可以嵌入到网页或Markdown中。 2 生成徽章2.1 编辑链接生成徽章 1 语法格式如下： 1https://img.shields.io/badge/<LABEL>-<MESSAGE>-<COLOR> 通过Shields语法规则生成徽章非常简单，<LABEL>-<MESSAGE>-<COLOR> 由三部分构成，中间通过 - 分隔。 <LABEL> :...
2020-03-14
SVN软件开发日志规范
SVN SVN软件开发日志规范前言： 写代码的好习惯除了言简意赅的注释外，还有完善且必要的日志。注释主要是对代码内的模块或功能函数、算法、逻辑框架等进行必要简明的说明，它关注的是”这个“代码里做了什么。而日志需要说明的是这版代码和上一版本改了什么（重点关注代码的升级迭代、用途、风险），和其他代码有啥关系（比如关注是否某些功能模块借鉴或移植于其他项目）。所以日志主要关注的是“这些”代码之间的关系（改动、移植），以及怎么用它，有何风险。所以不要觉得代码里写了足够的注释就不需要写Log了，经验丰富的软件开发们会形成自己完整的一套规范风格。 1...
2020-03-10
c代码Doxygen注释规范
c代码Doxygen注释规范前言： 良好得注释风格利于后期维护和团队协作开发，使得代码逻辑清晰，意图明了。Doxygen是一种能自动提取代码内注释生成版主文档的开源软件，它是跨平台的。非开源项目也许并不需要有这样一份帮助文档，但Doxygen的注释规范也不失为一种好的风格，可以推广遵守。 1 Doxygen注释规范模板1.1 文件注释模板123456789/** * @file 文件名（*.h/*.c） * @brief 该模块功能的简介。 * @details 使用该模块有哪些细节注意等。 * @author 创建该文件的人名。 * @data 该文件的创建日期（2020-03-10）。 * @version 文件或模块版本号（V1.0.0）。 * @copyright 版权所属公司。 */ 若某项无相关的说明，中文写 无 ，英文写 None ，此时末尾不加标点，若有相关的说明，则建议正常使用标点符号，包括句末标点。 1.2 函数注释模板1.2.1 完整格式1234567891011121314151617181920/** *...
2020-03-10
c代码命名规范
c代码命名规范前言： 为了兼容不同供应商的芯片驱动库，最好的办法是使用自定义的数据类型等，这样有利于代码的重用性和移植性。 1 变量命名1.1 命名前缀12345678910111213//类型宏定义，为了屏蔽不同芯片库文件的变量类型名称不一致，增强可移植性typedef _Bool Bool; //!< 布尔类型变量，变量命名时前缀加btypedef uint8_t Byte; //!< 1个字节无符号整型，变量命名时前缀加bytypedef uint16_t Word; //!< 2个字节无符号整型，变量命名时前缀加wtypedef uint32_t DWord; //!<...
2020-03-10
c代码文件内布局规范
c代码文件内布局规范 从上到下按如下布局代码： 1 *.h文件内代码布局规范 文件头注释。 文件条件编译宏。 头文件包含。 普通宏定义 结构体定义。 联合定义。 枚举定义。 宏定义。 全局变量声明。 全局函数声明。 宏函数定义。 2 *.c文件内代码布局规范 文件头注释。 头文件包含。 变量定义（按类型分类，从占字节少到字节多，然后是结构体、联合、枚举变量）。 函数定义。
2020-03-24
github issue提交Bug的格式
github issue提交Bug的格式前言： github早已在国内程序员中流行起来，我们经常会访问github上别人的源码或使用别人提供的插件，有时候会发现一些Bug希望作者能将其改进，这时候就可以考虑提交issue。 1...
评论
ValineGitalk
