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文件夹中。
[作者列表]：对于多人合作的项目，可以在这里简单介绍并感谢所有参与开发的研发人员。
[更新链接]：提供后续更新的代码链接。
[历史版本]：对历史版本更改记录做个简单的罗列，让用户直观的了解到哪些版本解决了哪些问题。
[联系方式]：可以提供微信、邮箱等联系方式，其他人对这个工程不明白的地方可以通过该联系方式与你联系。

README.md怎么写比较好相关推荐

github用相对路径显示图片_我写了一个开源工具, 让Github的README.md可以正常显示超大图片...
最终效果对比图片替换前: 图片显示有好有坏,能否显示,全凭运气图片替换后: 所有大图正常显示! 本项目永久开源地址痛点: Github的README.md展示图片效果并不完美为了让项目演示更生 ...
github README.md教程
github README.md教程总结 github中README.md通过特殊字符标记和缩进来达到格式控制,也可以用HTML标签来实现格式控制. 教程一: Markdown 的目标是实现「易读易 ...
GitHub上README.md教程
http://blog.csdn.net/kaitiren/article/details/38513715 最近对它的README.md文件颇为感兴趣.便写下这贴,帮助更多的还不会编写README文 ...
GitHub上README.md教程(copy)
[说明:转载于http://blog.csdn.net/kaitiren/article/details/38513715] 最近对它的README.md文件颇为感兴趣.便写下这贴,帮助更多的还不会编 ...
【转】GitHub上README.md教程
本文是转载文章,文章的来源:csdn博客博主:果冻虾仁文章: GitHub上README写法暨GFM语法解读博文地址:https://blog.csdn.net/guodongxiaren/ar ...
DuangDuangDuang！码云项目的 Readme.md 特殊技能
为什么80%的码农都做不了架构师?>>> 我们在码云上创建新项目的时候,常常会看到默认使用 README 文件初始化该项目(如图1 所示),然后在新建项目的根目录下就会生成 ...
【Git】GitHub设置README.md引用本repo目录下的图片
我们在完善GitHub的repo时,往往需要完善其README.md.图片是一种表现力较强的呈现形式,引入图片也是Markdown支持的语法,因此有时候我们需要将一些图片放在README.md中显示给 ...
md 生成目录码云_DuangDuangDuang！码云项目的 Readme.md 特殊技能
原标题:DuangDuangDuang!码云项目的 Readme.md 特殊技能我们在码云上创建新项目的时候,常常会看到默认使用 README 文件初始化该项目(如图1 所示),然后在新建项目的 ...
git笔记之README.md格式
初次使用git,想修改远程仓库中README.md格式,于是度娘一下,发现,尽然有自己的格式,如下: 1 标题与文字格式标题 # 这是 H1 <一级标题> ## 这是 H2 <二级 ...

README.md怎么写比较好

README.md的作用

命名规范

内容结构

README.md怎么写比较好相关推荐

最新文章

热门文章