为开发项目编写规范的README文件

た入场券 2022-11-06 14:53 458阅读 0赞

### README ###

*   *  1.README.md的重要性：
     *  2.主要内容：
     *   *   *   *  其他关键信息：
                 *  涉及到的工具：
     *  3.demo
     *   *   *   *   *  项目描述
                     *  环境依赖
                     *  部署步骤
                     *  目录结构
                     *  V1.0.0 版本内容更新
                     *  了解更多

## 1.README.md的重要性： ##

1、过了很长时间后，仍然知道代码里，当初写了什么；  
2、其他人看代码时不需要那么费劲；  
3、代码的质量就大大的提高；

## 2.主要内容： ##

1、软件定位，软件的基本功能；  
2、代码目录结构说明  
3、运行环境、三方依赖  
4、运行代码的方法：安装，运行，部署等等；  
5、简要的使用说明；  
6、文档地址，比如swagger  
7、更详细点可以说明软件的基本原理；  
8、常见问题说明

##### 其他关键信息： #####

项目和所有子模块和库的名称；
    对所有子模块和库的描述；
    如何使用某库；
    版权信息和许可信息；
    抓取文档指令；
    安装、配置和运行程序的指导；
    抓取最新代码和构建他们的说明（或快速概述和阅读Install）
    作者列表；
    提交bug；
    其他联系信息；（电子邮箱，网站，公司名称，地址）
    一个简短的历史纪录；
    法律声明。

##### 涉及到的工具： #####

**生成项目结构：**

全局安装 `tree` 这个组件
    然后直接执行：`tree > tree.text`
    就会在执行的这个目录下生成一个tree.text,里边就是全部目录结构
    如果想要忽略一些文件，比如前端可能有node-modules，执行：`tree -I node_modules > tree.text`

## 3.demo ##

###### 项目描述 ######

xxxxxx

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

node v0.10.28+  
redis ~

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

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

###### 了解更多 ######

url,url,…