描述主题

简介

描述主题是编程中常见的任务之一。它是指让开发人员根据需求和规范，以清晰、准确、简洁的语言将一个算法、模块或系统的行为特性进行详细的叙述。

良好的描述能够帮助团队成员理解你的代码、提高代码质量、减少沟通成本。也有助于在修改代码前有一个全局的认识和了解，提高代码的可读性和可维护性。因此，在编写任何代码之前，撰写清晰、详细、简明扼要的描述是至关重要的。

内容

要编写一个好的描述，需要详细的思考以下问题：

1. 描述的是什么？是一个函数、类、模块、系统，还是所有这些的组合？
2. 描述的目的是什么？是帮助其他开发者理解你的代码，还是帮助你自己回忆和理解代码？
3. 描述的具体内容包括什么？输入、输出、算法流程或业务逻辑？

针对不同的任务，描述的内容和格式也会有所不同。例如，当你描述一个函数时，你需要提供输入和输出的数据结构、数据类型和含义以及函数如何处理这些数据。

## 函数名

描述函数的功能和输入、输出

### 输入

描述输入数据结构、类型和含义：

- `arg1` : int，表示xxx的数量
- `arg2` : str，表示xxx的名称

### 输出

描述输出数据结构、类型和含义：

- `res` : dict，表示xxx的统计结果，包括以下字段：

  - `count` : int，表示xxx的数量
  - `name` : str，表示xxx的名称

  最终结果为一个字典 `res`。

### 示例

提供代码示例以及函数调用的结果：

```python
def my_function(arg1: int, arg2: str) -> dict:
    ...
    
print(my_function(10, 'apple'))

{'count': 10, 'name': 'apple'}

说明

其他需要注意的说明事项，如函数调用的限制、关键算法流程等。

## 结论

清晰、概括、简明扼要的描述能够帮助团队成员理解你的代码、提高代码质量、减少沟通成本。编写好的描述不仅有助于你的团队，也为其他开发者提供了一个良好的文档模板，更容易接入你的项目并使用你的代码。