软件开发规范的那些事

软件开发一般是多个人协作开发的，不同人的习惯和方式都不同，没有统一的规范就会造成非常多的问题，比如：代码风格不一致、目录杂乱无章、接口定义不统一、错误码不规范。

一个好的规范不仅可以提高软件质量，还可以提高开发效率，降低维护成本，甚至减少 Bug。在不同的项目和团队时，所要求的规范一般是不一样的，这篇文章中我会尽量总结一些最常见、最通用的规范。

通常情况下，有哪些方面的内容需要去设计规范呢？从项目和编码不同的维度，可以根据是否跟代码有关，分为：

• 非编码类规范：开源规范、文档规范、版本规范、Commit 规范、发布规范
• 编码类规范：目录规范、代码规范、日志规范、接口规范、错误码规范

开源规范

只有开源项目，才需要关注开源规范。关于开源协议，我们平时也有或多或少的接触，但真的理解各种开源协议的具体内容和作用细节么？

开源协议，其实就是规定了你在使用开源软件时的权利和责任。业界的开源协议有很多，我们只需要了解下边经常使用的 6 种协议就可以了。

常见的几种开源协议：GPL、MPL、LGPL、Apache、BSD、MIT，如下图所示，右边的协议比左边的协议宽松，在选择时可以根据菱形框中的选项从上到下进行选择。

如果你想了解更详细的开源规范，可以看 这份资料。

文档规范

工作中发现，大多数的程序员都不爱写文档，觉着没有文档也没有啥问题。其实文档属于软件交付的一项重要内容，没有文档项目就很难理解、使用、部署和运维。

编写文档是一个必不可少的开发工作，一个项目需要编写哪些文档，该如何编写呢？三类常见且重要的文档，包括：Readme文档、项目文档、API 接口文档

1. README文档

打开一个项目后，最先关注到的就是 README 文档，一般放在项目的根目录下，它主要是用来介绍项目的功能、安装、使用的。

可以大概包含如下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

## 项目名称
<!-- 写一段简短的话描述项目 -->
## 功能特性
<!-- 描述该项目的核心功能点 -->
## 快速开始
#### 依赖检查
<!-- 描述该项目的依赖，比如依赖的包、工具或其它任何依赖项 -->
#### 如何构建
<!-- 描述如何构建该项目 -->
#### 如何运行
<!-- 描述如何运行该项目 -->
## 使用指南
<!-- 描述如何使用该项目 -->
## 如何贡献
<!-- 告诉其他开发者如何给该项目贡献代码 -->
## 关于作者
<!-- 这里写上项目作者 -->
## 许可证
<!-- 这里链接上该项目的开源许可证 -->

更具体的示例，可以参考这个 README.md 文件。这儿有个在线的 README 生成工具，也可以参考 readme.so。

2. 项目文档规范

项目文档，一般包括开发文档和用户文档，通常放在 /docs 目录下。

• 开发文档：用来说明项目的开发流程，比如如何搭建开发环境、构建二进制文件、测试、部署等；
• 用户文档：软件的使用文档，对象一般是软件的使用者，可以包括 api 文档、sdk 文档、安装文档、功能介绍、最佳实践、操作指南、常见问题等；

一般的项目文档结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

docs
├── devel                # 开发文档
│   └── development.md
├── guide                # 用户文档
│   ├── api/             # API文档
│   ├── faq/             # FAQ文档
│   ├── sdk/             # SDK文档
│   ├── best-practice/   # 最佳实践
│   ├── operation-guide/ # 操作向导
│   ├── installation.md  # 安装说明
│   ├── introduction.md  # 产品介绍
│   ├── quickstart.md    # 快速开始
│   └── README.md        # 用户文档入口
└── images               # 存放图片
    └── arch-v1.png

3. API接口文档规范

接口文档一般有 4 种编写方式，包括编写 word 格式文档、借助工具编写、通过注释生成、编写 md 格式文档。

一个规范的 API 接口文档，通常需要包含：完整的 API 接口介绍文档、API 接口变更历史文档、通用说明、数据结构说明、错误码描述和 API 接口使用文档。API 接口使用文档需要包含接口描述、请求方法、请求参数、输出参数和请求示例。

接口文档一般可拆分几个 md 文件，存放在 docs/guide/api 目录中

• README.md：API 接口介绍文档，会分类介绍项目支持的 API 接口，并会存放相关 API 接口文档的链接，方便开发者查看；
• CHANGELOG.md：API 接口文档变更历史，方便进行历史回溯，也可以使调用者决定是否进行功能更新和版本更新；
• generic.md：用来说明通用的请求参数、返回参数、认证方法和请求方法等；
• struct.md：列出使用的数据结构，这些数据结构可能被多个 API 接口使用；
• api.md：API 接口文档，相同 REST 资源的接口会存放在一个文件中，以 REST 资源名命名文档名；
• error_code.md：错误码描述，通过程序自动生成；

下边简单介绍接口文档包含哪些必要的内容：

• 接口描述：描述接口实现了什么功能
• 请求方法：例如 POST /v1/users
• 输入参数：接口的输入字段，包括 Header参数、Query参数、Body参数、Path参数。每个字段通过 参数名称、必选、类型、描述 属性来描述，如果参数有限制或默认值，可以在描述部分注明
• 输出参数：接口的返回字段，每个字段通过 参数名称、类型、描述 属性来描述
• 请求示例：一个真实的 API 接口请求和返回示例

更详细的示例可以参考 这份示例

版本规范

版本机制，可以通过版本号，可以定位该组件的功能和代码，方便定位问题。二是携带版本号，可以让使用者知道目前的项目进度，以及使用版本和上一个版本的功能差别。

语义化版本格式为：主版本号.次版本号.修订号（X.Y.Z）

• 主版本号：当做了不兼容的 API 修改
• 次版本号：当做了向下兼容的功能性新增及修改
• 修订号：当做了向下兼容的的问题修改

软件发布后，禁止改变该版本软件的内容，任何修改都必须以新版本发行。0.y.z 软件处于开发初始阶段，被视为不稳定版本，一般 1.0.0 版本号被界定为第一个稳定版本。

在实际项目开发时，建议使用 0.1.0 作为第一个开发版本号，并在后续每次发行时递增次版本号。当我们严格按照规范提交代码时，版本号可以这么来确定

• fix 类型的 commit 可以将修订号 +1
• feat 类型的 commit 可以将次版本号 +1
• 带有 BREAKING CHANGE 的 commit 可以将主版本号 +1

上一篇 « 配置 docker 镜像加速器 下一篇 » 如何安装PHP环境及相关概念