README(注释和说明文档)
1. 为什么要有README文档**
简评:因为 README,6 个月后的你仍然知道当初写了什么;因为 README,其他人看一眼就能知道是否需要;因为 README,让你的代码更有质量;因为 README,你成了个作家。
README 是一种说明文件,通常随着一个软件而发布,里面记载有软件的描述或注意事项。这种档案通常是一个纯文字文件,被命名README.TXT、README.1ST或http://READ.ME等等;但也有RTF或DOC格式的读我档案。
2. README文档内容结构
- [功能描述]:主要描述一下这个项目的主要功能列表。
- [开发环境]:罗列使用本工程项目所需要安装的开发环境及配置,以及所需软件的版本说明和对应的下载链接。
- [项目结构简介]:简单介绍项目模块结构目录树,对用户可以修改的文件做重点说明。
- [测试DEMO]:此处可以简单介绍一下DEMO程序的思路,具体实现代码放在example文件夹中。
- [作者列表]:对于多人合作的项目,可以在这里简单介绍并感谢所有参与开发的研发人员。
- [更新链接]:提供后续更新的代码链接。
- [历史版本]:对历史版本更改 记录做个简单的罗列,让用户直观的了解到哪些版本解决了哪些问题。
- [联系方式]:可以提供微信、邮箱等联系方式,其他人对这个工程不明白的地方可以通过该联系方式与你联系
3. 好的README文档
3.1 建议命名方式——大写英文字母
它的档名通常是以大写英文来命名的,因为大写英文字母比小写有着较小的ASCII码;亦因此在一些以ASCII排序档案的环境里,它能被保证被列在档案列表的第一位。这种档案的特殊命名使任何人能第一时间发现并阅读这个档案,即使他们本身并没有关于 README 的相关知识。
3.2 README 应该要简洁而清晰
- 告诉他们这是什么(包括背景介绍)
- 向他们展示实际使用的样子
- 传授使用方法
- 告知其他可能相关的细节
举个栗子:
DEMO
===========================
###########环境依赖
node v0.10.28+
reids ~
###########部署步骤
1. 添加系统环境变量
export $PORTAL_VERSION="production" // production, test, dev
2. npm install //安装node运行环境
3. gulp build //前端编译
4. 启动两个配置(已forever为例)
eg: forever start app-service.js
forever start logger-service.js
###########目录结构描述
├── Readme.md // help
├── app // 应用
├── config // 配置
│ ├── default.json
│ ├── dev.json // 开发环境
│ ├── experiment.json // 实验
│ ├── index.js // 配置控制
│ ├── local.json // 本地
│ ├── production.json // 生产环境
│ └── test.json // 测试环境
├── data
├── doc // 文档
├── environment
├── gulpfile.js
├── locales
├── logger-service.js // 启动日志配置
├── node_modules
├── package.json
├── app-service.js // 启动应用配置
├── static // web静态资源加载
│ └── initjson
│ └── config.js // 提供给前端的配置
├── test
├── test-service.js
└── tools
###########V1.0.0 版本内容更新
1. 新功能 aaaaaaaaa
2. 新功能 bbbbbbbbb
3. 新功能 ccccccccc
4. 新功能 ddddddddd
其他栗子:Apache HTTP Server和GNU的README文档都很简洁