Linux教程网

软件开发规范的那些事

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

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

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

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

开源规范

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

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

常见的几种开源协议:GPLMPLLGPLApacheBSDMIT,如下图所示,右边的协议比左边的协议宽松,在选择时可以根据菱形框中的选项从上到下进行选择。

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

文档规范

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

编写文档是一个必不可少的开发工作,一个项目需要编写哪些文档,该如何编写呢?三类常见且重要的文档,包括: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

详细的语义化版本规范内容参考 这个文档


专题:

本文发表于 2024-03-04,最后修改于 2024-12-06。

本站永久域名「 golinuxblog.com 」,也可搜索「 Linux教程网 」找到我。


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

推荐阅读

Big Image