如何编写优雅的commit message

博主：小蓝
发布时间：2024 年 10 月 25 日
19 次浏览
暂无评论
3690字数
分类： Linux 技术杂烩

在团队合作中，一个**优雅的 commit message** 不仅仅是代码的一部分，它更是团队之间沟通的重要媒介。通过清晰且有条理的 commit message，团队成员可以更好地理解每个代码变更的原因及内容。本文将为你详细介绍如何编写优雅的 commit message，并为你提供一些实用的技巧和模板。

## 一、为什么需要优雅的 Commit Message

- **提高代码可读性和维护性**：优雅的 commit message 有助于后续的代码维护，团队成员可以迅速了解每次代码变更的目的和内容。
- **便于代码审查**：清晰的 commit 信息可以帮助代码审查者更好地理解提交的内容，从而提高代码审查的效率。
- **提高项目文档的质量**：每条 commit message 都可以看作是项目文档的一部分，优雅的 commit message 帮助构建更详细的变更历史。

## 二、Commit Message 的基本结构

一个完整的 commit message 通常由三部分组成：

1. **标题（subject）**：简洁描述变更内容。
2. **正文（body）**：进一步描述变更的详细信息（可选）。
3. **脚注（footer）**：用于标注解决的问题、关联的任务编号等（可选）。

以下是推荐的 commit message 结构：

```text
<type>: <subject>

<body>

<footer>
```

- **标题**：通常限制在 50 个字符以内，首字母大写，尽量简洁明了。
- **正文**：如果变更较为复杂，可以在正文中详细说明。
- **脚注**：脚注用于关联问题或任务，通常用于修复 bug 或实现特定功能。

### 示例：

```text
feat: 添加用户登录功能

实现了用户登录接口，包含用户名和密码的验证逻辑，增加了 JWT 认证机制。
修复了在验证失败时的错误信息不准确问题。

Closes #123
```

## 三、Commit Message 的类型说明

为了让每个 commit 更具可读性和一致性，推荐使用以下几种**类型标签**：

| 类型               | 含义                                   | 示例                                     |
| ------------------ | -------------------------------------- | ---------------------------------------- |
| **feat**     | 新功能                                 | `feat: 添加用户注册功能`               |
| **fix**      | 修复 bug                               | `fix: 修复登录时未能正确跳转的问题`    |
| **docs**     | 文档变更                               | `docs: 更新 README 中的安装说明`       |
| **style**    | 格式变更（不影响代码逻辑）             | `style: 格式化代码使其符合 lint 规则`  |
| **refactor** | 代码重构（既不增加功能，也不修复 bug） | `refactor: 重构数据处理逻辑以提高性能` |
| **test**     | 增加测试                               | `test: 添加登录功能的单元测试`         |
| **chore**    | 其他杂项                               | `chore: 更新项目依赖版本`              |

### 选择合适的类型

- **功能新增**、**功能更新**使用 `feat`。
- **问题修复**使用 `fix`。
- **代码格式或注释**变更，不改变逻辑使用 `style`。

## 四、如何编写优雅的标题（Subject）

- **简洁明了**：限制在 50 个字符以内，清晰地描述变更内容。
- **使用动词**：标题一般以动词开头，例如“添加”、“修复”、“优化”等。
- **首字母大写**：保持风格一致性。
- **避免使用结尾标点符号**：标题应尽量保持简短，避免使用结尾的句号。

### 示例对比

- 不优雅的标题：`更改了一些代码`
- 优雅的标题：`refactor: 改进数据处理逻辑，减少重复计算`

## 五、编写正文（Body）时的注意事项

- **详细描述变更的背景和原因**：如果变更较为复杂，可以在正文中详细描述为什么需要做出这个更改。
- **解释代码的变更**：尽量解释代码的逻辑变更，而不是代码本身。例如：“为了提高数据处理的性能，将 XXX 算法从线性改为对数复杂度。”
- **换行规范**：正文应尽量保持每行不超过 72 个字符，以便于阅读。

### 示例：

```text
fix: 修复用户登录失败时的错误提示不准确

之前的登录失败提示信息过于模糊，用户无法了解具体的失败原因。
本次提交增加了具体的错误信息，例如用户名不存在或密码错误。
```

## 六、编写脚注（Footer）

脚注部分主要用于关联问题、任务编号或其他有用的信息，常见的脚注关键字有：

- **Closes**：标明该提交解决了某个问题或任务。
- **Refs**：引用与本次提交相关的任务，但并未完全解决。

### 示例：

```text
feat: 添加用户评论功能

实现了文章下方的用户评论模块，支持 Markdown 格式，包含评论的增删改查功能。

Closes #456
```

## 七、良好的 Commit Message 示例

### 示例一

```text
refactor: 优化数据库查询逻辑

减少了冗余查询，使用缓存来存储重复查询的数据，从而降低了数据库的压力。
```

### 示例二

```text
fix: 修复购物车结算时价格计算错误的问题

修复了因商品折扣计算错误导致的总价偏差问题，确保每次结算时价格准确。
```

### 示例三

```text
docs: 补充接口文档中的示例代码

增加了用户注册接口的使用示例，帮助开发者更好地理解接口的用法。
Refs #789
```

## 八、Commit Message 编写指南

为了更好地编写 commit message，建议遵循以下**工作流程**：

```mermaid
graph TD
    A[开始开发] --> B[代码变更完成]
    B --> C[选择 commit 类型]
    C --> D[编写简洁明了的标题]
    D --> E[必要时编写详细正文]
    E --> F[添加脚注关联任务]
    F --> G[提交 commit]
```

## 九、常见错误与避免方法

- **过于模糊的描述**：如“修改了一些代码”。应避免使用这种描述，而是清楚地说明变更的具体内容。
- **拼写或语法错误**：拼写错误不仅会影响阅读体验，还可能导致误解，因此在提交前应仔细检查拼写和语法。
- **多个变更合并在一个 commit 中**：每次提交应尽量保持单一职责，避免将多个不相关的变更合并在一起。

## 十、总结

**优雅的 commit message** 不仅仅是代码历史的记录，也是团队沟通、协作的重要工具。通过使用清晰的结构、合适的类型标签，以及简洁的描述，可以让代码的维护和审查变得更加轻松。

以下是编写优雅 commit message 的**关键点**：

- **保持简洁**，标题不超过 50 个字符。
- **选择合适的类型标签**，如 `feat`、`fix` 等。
- **提供详细正文**，在变更复杂时描述原因和解决方案。
- **关联任务或问题**，使用 `Closes #` 或 `Refs #`。

在团队协作中，优雅的 commit message 可以让每个人更好地理解项目的进展和变更，提升团队的效率和代码质量。😊

蓝易云是一家专注于香港及国内数据中心服务的提供商，提供高质量的服务器租用和云计算服务、包括免备案香港服务器、香港CN2、美国服务器、海外高防服务器、国内高防服务器、香港VPS等。致力于为用户提供稳定,快速的网络连接和优质的客户体验。

最后修改：2024 年 10 月 25 日

如果觉得我的文章对你有用，请随意赞赏

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

评论 *

私密评论

名称 *

🎲

邮箱 *

地址

如何编写优雅的commit message

小蓝 • 2024 年 10 月 25 日

## 一、为什么需要优雅的 Commit Message

## 二、Commit Message 的基本结构

一个完整的 commit message 通常由三部分组成：

以下是推荐的 commit message 结构：

```text
<type>: <subject>

<body>

<footer>
```

### 示例：

```text
feat: 添加用户登录功能

实现了用户登录接口，包含用户名和密码的验证逻辑，增加了 JWT 认证机制。
修复了在验证失败时的错误信息不准确问题。

Closes #123
```

## 三、Commit Message 的类型说明

为了让每个 commit 更具可读性和一致性，推荐使用以下几种**类型标签**：

### 选择合适的类型

- **功能新增**、**功能更新**使用 `feat`。
- **问题修复**使用 `fix`。
- **代码格式或注释**变更，不改变逻辑使用 `style`。

## 四、如何编写优雅的标题（Subject）

### 示例对比

- 不优雅的标题：`更改了一些代码`
- 优雅的标题：`refactor: 改进数据处理逻辑，减少重复计算`

## 五、编写正文（Body）时的注意事项

### 示例：

```text
fix: 修复用户登录失败时的错误提示不准确

之前的登录失败提示信息过于模糊，用户无法了解具体的失败原因。
本次提交增加了具体的错误信息，例如用户名不存在或密码错误。
```

## 六、编写脚注（Footer）

脚注部分主要用于关联问题、任务编号或其他有用的信息，常见的脚注关键字有：

- **Closes**：标明该提交解决了某个问题或任务。
- **Refs**：引用与本次提交相关的任务，但并未完全解决。

### 示例：

```text
feat: 添加用户评论功能

实现了文章下方的用户评论模块，支持 Markdown 格式，包含评论的增删改查功能。

Closes #456
```

## 七、良好的 Commit Message 示例

### 示例一

```text
refactor: 优化数据库查询逻辑

减少了冗余查询，使用缓存来存储重复查询的数据，从而降低了数据库的压力。
```

### 示例二

```text
fix: 修复购物车结算时价格计算错误的问题

修复了因商品折扣计算错误导致的总价偏差问题，确保每次结算时价格准确。
```

### 示例三

```text
docs: 补充接口文档中的示例代码

增加了用户注册接口的使用示例，帮助开发者更好地理解接口的用法。
Refs #789
```

## 八、Commit Message 编写指南

为了更好地编写 commit message，建议遵循以下**工作流程**：

## 九、常见错误与避免方法

## 十、总结

以下是编写优雅 commit message 的**关键点**：

在团队协作中，优雅的 commit message 可以让每个人更好地理解项目的进展和变更，提升团队的效率和代码质量。😊

如何编写优雅的commit message

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

微信视频号视频下载工具WeChatVideoDownloader

Win11系统优化工具-Windows11一键设置

Windows微软常用运行库合集一键安装

【电脑软件】Google翻译修复工具

Windows版Kangle安装教程及安装包

ssh登录22号端口拒绝连接Ubuntu?

MySQL数据库如何连接到远程服务器上的数据库。

在Ubuntu(WSL)中管理openssl版本：安装与卸载指导

【Linux工具】-yum/gdb使用教程！

如何在Ubuntu上安装MongoDB？

如何编写优雅的commit message

发表评论 取消回复 使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

如何编写优雅的commit message

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款