如何为开发项目编写规范的README文件（windows），此文详解

2022-11-09 09:17:45

为什么要写这篇博客？

　　其实我是一个入坑已经半年的程序员，因为不是计算机专业，只能自己摸索，所以我深知博客的重要性。每次我的学习笔记啊，项目的，面试题啊，有的，只要有时间，我肯定上传上来，一方面自己可以随时随地的看，另一方面也可以方便大家。

　　了解一个项目，恐怕首先都是通过其Readme文件了解信息。如果你以为Readme文件都是随便写写的那你就错了。github，oschina git gitcafe的代码托管平台上的项目的Readme.MD文件都是有其特有的语法的。称之为Markdown语法，今天要写的是关于README文件在windows中如何写，怎么写出来才符合要求，写出来才好看，这样就不得不说一下MarkDown编译器了。

　　也许很多大神说，Markdown这么简单的，还需要写个博客炫耀？

　　其实你错了，对于我们这些在windows上操作惯了的野路子，根本对除了word之外的编辑语言不感冒，也不习惯，但是每次项目都会需要README文件，记得我第一次写的README文件是TXT格式，被老师嘲笑了，说README文件是.md格式，但是我自己比较笨，请教了一个哥们，终于知道了写README的好方法，那就是使用mardkdown工具，我下载的是有道云笔记（我还用的是windows操作系统），他不但有MARKDOWN，更重要的是，还有MarkDown使用指南，（大家不要误会，我不是推销这个软件，对于还是小白的我，觉得遇到了神器，很激动）。既然有这个了，那么我的问题就迎刃而解了。

　　这篇文说到这里，这才刚刚开始，下面主要介绍一下 MarkDown的主要用法，方便大家写README文件。

为什么要写README文件？

　　对于这个问题详解，请看博客：http://www.cnblogs.com/wj-1314/p/7551184.html

　　这个问题很简单，因为README的编写，过了很长时间后，你仍然知道你当初写了什么；因为README的编写，其他人看你的代码不需要那么费劲；因为README的编写，你代码的质量就大大的提高；因为README的编写，你的语言水平就大大的提高了。

　　所以说README应该简短，大家不要以为写这个很麻烦，这个东西能够节省你和别人的很多时间。

完整的README包括什么内容？

　　关于README的内容，这是我觉得是每个项目中都应该有的一个文件，目的是能简要的描述该项目的信息，让读者快速了解这个项目。

一，它需要说以下几个事项：

1，软件定位，软件的基本功能

2，运行代码的方法：安装环境，启动命令等

3，简要的使用说明

4，代码目录结构说明，更详细点可以说明软件的基本原理

5，常见问题说明

二，它包括了一下内容：

项目和所有子模块和库的名称（对于新用户，有时不同命名会导致混乱）

对所有项目，和所有子模块和库的描述

如何使用 5-line code（如果是一个库）

版权和许可信息（或阅读许可证）

抓取文档指令

安装、配置和运行程序的指导

抓取最新代码和构建它们的说明（或快速概述和「阅读 Install」）

作者列表或「Read AUTHORS」

提交bug，功能要求，提交补丁，加入邮件列表，得到通知，或加入用户或开发开发区群的介绍

其他联系信息（电子邮件地址，网站，公司名称，地址等）

一个简短的历史记录（更改，替换或者其他）

法律声明

3，一个简单的范本（当然，我们前期写的话，不必要那么麻烦，就写几个简单的必要的东西，比如法律声明啊，联系记录啊等等，就不必要写）

DEMO

===========================

###########环境依赖

node v0.10.28+

redIs ~

###########部署步骤

. 添加系统环境变量

    export $PORTAL_VERSION="production" // production, test, dev

. npm install  //安装node运行环境

. gulp build   //前端编译

. 启动两个配置(已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 版本内容更新

. 新功能     aaaaaaaaa

. 新功能     bbbbbbbbb

. 新功能     ccccccccc

. 新功能     ddddddddd