代码文档

为您的团队和您未来的自己代码文档。

Intuition

代码告诉你_怎么_做，注释告诉你_为什么_。——杰夫·阿特伍德

可以通过代码文档来进一步组织代码，让其他人（以及未来的自己）更容易轻松地导航和扩展它。在完成编写代码库的那一刻就最了解代码库，但幸运的是，记录它将使能够快速回到熟悉的心态。文档对开发人员来说可能意味着很多不同的东西，所以让定义最常见的组件：

• comments：关于为什么存在一段代码的简短描述。
• typing：函数输入和输出数据类型的规范，提供与函数消耗和产生的内容有关的信息。
• docstrings：对描述整体效用、参数、返回等的函数和类的有意义的描述。
• docs：呈现的网页，总结了所有的功能、类、工作流程、示例等。

目前，将在本地生成文档，但请务必查看应用程序的自动生成文档页面。每次对代码库进行更改时，将在CI/CD课程中学习如何自动创建文档并使其保持最新。

代码协作

您目前如何与团队中的其他人共享您的代码？有什么可以改进的？

Typing

对代码尽可能明确是很重要的。已经讨论过为变量、函数等选择显式名称，但可以显式的另一种方法是为函数的输入和输出定义类型。

到目前为止，函数看起来像这样：

def some_function(a, b):
    return c

但是可以使用打字来合并更多信息：

from typing import List
def some_function(a: List, b: int = 0) -> np.ndarray:
    return c

在这里定义了：

• 输入参数 a是一个列表
• 输入参数 b是一个整数，默认值为0
• 输出参数