README.md怎么写比较好

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文本文档那样没有格式,会造成阅读混乱。

内容结构

  1. [功能描述]:主要描述一下这个项目的主要功能列表。
  2. [开发环境]:罗列使用本工程项目所需要安装的开发环境及配置,以及所需软件的版本说明和对应的下载链接。
  3. [项目结构简介]:简单介绍项目模块结构目录树,对用户可以修改的文件做重点说明。
  4. [测试DEMO]:此处可以简单介绍一下DEMO程序的思路,具体实现代码放在example文件夹中。
  5. [作者列表]:对于多人合作的项目,可以在这里简单介绍并感谢所有参与开发的研发人员。
  6. [更新链接]:提供后续更新的代码链接。
  7. [历史版本]:对历史版本更改 记录做个简单的罗列,让用户直观的了解到哪些版本解决了哪些问题。
  8. [联系方式]:可以提供微信、邮箱等联系方式,其他人对这个工程不明白的地方可以通过该联系方式与你联系。
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值