README.md的作用
README.md文件是一个项目的入门手册,里面介绍了整个项目达到什么样子的效果、需要搭建什么样的环境、具备什么样的技能等等。所以README文件写得好不好,关系到这个项目能不能更容易的被其他人使用。下面详细的介绍一下README.md文件要怎么写可以更好更直观。
命名规范
在github,gitlab等代码托管服务器上创建一个仓库时,服务器一般会建议在代码工程中添加一个README.md文件,大家应该会有这样的疑问,为什么这个文件名不是readme.md, readme.txt等等。以下是个人几点看法:
(1) README采用全大写,主要是可以跟代码文件直观的区分开,readme.md乍一看有点像是代码文件,不够直观。这不够体现出它优先其他工程文件被阅读的初衷。
方式一
main.c
main.h
helloworld.c
helloworld.h
README.md
方式二
main.c
main.h
helloworld.c
helloworld.h
readme.md
以上两种文件目录可以看到,如果代码文件很多的时候,readme文件是比较难找到的,所以建议名称采用全大写。
(2) 'R'的ASCII码为0x52,'r'的ASCII码为0x72,这有利于在排序时README.md会比较靠前。
(3) README文件的后缀名采用是.md。该种后缀的文件主要是采用markdown规则编写的。采用markdown规则可以很方便的在文本中添加格式,编写的关注点转移到文档内容本身,而不需要像富文本那样要一直修改内容格式,或者像txt文本文档那样没有格式,会造成阅读混乱。
内容结构
- [功能描述]:主要描述一下这个项目的主要功能列表。
- [开发环境]:罗列使用本工程项目所需要安装的开发环境及配置,以及所需软件的版本说明和对应的下载链接。
- [项目结构简介]:简单介绍项目模块结构目录树,对用户可以修改的文件做重点说明。
- [测试DEMO]:此处可以简单介绍一下DEMO程序的思路,具体实现代码放在example文件夹中。
- [作者列表]:对于多人合作的项目,可以在这里简单介绍并感谢所有参与开发的研发人员。
- [更新链接]:提供后续更新的代码链接。
- [历史版本]:对历史版本更改 记录做个简单的罗列,让用户直观的了解到哪些版本解决了哪些问题。
- [联系方式]:可以提供微信、邮箱等联系方式,其他人对这个工程不明白的地方可以通过该联系方式与你联系。