手记
下载APP

项目说明文档编写规范

Markdown 的使用可以按需要参考:

规范1:使用 Markdown 编写说明文档

为了更好的利用 Git 管理项目,一定要使用 Markdown 来编写项目说明文档,而不是使用 .docx 等格式的文件编写项目说明文档(Git 无法管理细节)。不要使用 .txt 用来管理项目说明文档,它的功能太单一,同时可能会引入一些编码错误问题,而相对的 Markdown 功能可以满足大多数项目开发的需求,支持图片,网址,以及音频的插入,并且也可以导入流程图。Markdown 的语法并不复杂,很容易上手,支持将其转换为 pdfdocx 等格式文档。Markdown 可以直接作为幻灯片进行展示。

规范2:按照目录树编写说明文档

为了更好地模块化管理项目,不推荐仅仅使用一个目录用来存放项目,应该将项目按照模块或者功能分割为不同目录。这些目录形成了具有等级的目录树,为了项目的清晰,最好在每个目录下均存放一个 README.md 文件用来记录该目录的功能与修改记录(重大修改)。

规范3:单个 README.md 文件的编写规范

  1. 在文档中简略介绍该目录做了什么(What),为什么这样做(Why),怎么做的(How)。
  2. 在项目根目录的 README.md 需要交代涉及版权问题的一些内容。
  3. 引入 hotfix.md,并将重大修改编写进 README.md

规范4:hotfix.md 文件的编写规范

项目并不是一天建成的,需要在 hotfix.md 文件中记录项目开发过程中出现的问题与解决策略。下面是一个例子:

# teacher helper 版本更新记录

抠图辅助软件工具:teacher helper

## v0.2

1. 修复 v0.1 版本的中文路径输出显示乱码问题。(v0.2.1@xinet:2019/7/26)
2. 修复 代码部分逻辑问题。(v0.2.2@xinet:2019/7/27)

## v1.0(v1.0.1@xinet:2019/8/5)

- 将 `检查` 按钮改为 `审查`,输出的 `errors.txt` 更名为 `checkout.txt`;
- 重构了代码的逻辑,提高代码的容错能力;
- 增加对 负样本 的搜索功能。

v0.2.2@xinet:2019/7/27v0.2.2 表示版本号,xinet 表示责任者,2019/7/27 表示修改的时间。

更多与项目开发相关的内容参考:xinetzone/projects

小 Tips:

如果你要查看文件的每个部分是谁修改的,那么 git blame 就是不二选择. 只要运行 git blame [filename],你就会得到整个文件的每一行的详细修改信息:包括 SHA 串,日期和作者。

$ git blame -L 160,+10 sha1_file.c

其中 -L 160,+10 用来限制显示的行数,详细参考 http://gitbook.liuhui998.com/index.html

打开App,阅读手记
5人推荐
随时随地看视频慕课网APP