结构化你的项目外文翻译资料

结构化你的项目

关键词：结构化，模块，Python

我们所说的“结构化”，是指如何使你的项目最好地满足它的对象性。我们需要去考虑如何更好地利用 Python 的特性来创建整洁、高效的代码。从实践角度讲，“结构化”意味着编写整洁的代码，使它的逻辑、依赖关系、文件和目录在文件系统中的组织方式都保持清晰。

哪些函数应该放入到哪些模块？数据如何在项目中流转？哪些函数和功能可以组合并抽离？通过回答这些问题，你可以开始计划，宏观的看，你最终的产品将是什么样子。

在本节中，我们将进一步了解 Python 的模块和导入系统，因为它们是在项目中贯彻结构化的核心要素。接下来，我们将从不同层面讨论如何构建可扩展、可靠的代码。

1 仓库的结构

1.1 这很重要

就像代码风格，API 设计和自动化对一个健康的开发周期是必不可少的。仓库的结构正是项目架构的关键部分。

当一个潜在的用户或贡献者登录到您的仓库页面时，他们会看到一些信息:

• 项目名称
• 项目介绍
• 一系列的文件

只有当他们滚动到目录下方时，才会看到你项目的 README。

如果你仓库是大量的文件或混乱的文件目录，没有清晰的结构，他们可能四处翻找后才会看到你写的优雅文档。

“为你期望的工作精心打扮，而不是为你现在的工作。”

当然，第一印象并不是一切。但是，你和你的同事将在这个仓库中工作很长时间，熟悉它的每一个角落和细节。拥有良好的结构将事半功倍。

1.2 仓库示例

请看这里: 这是 Kenneth Reitz 在2013年推荐的。

这个仓库可以在 GitHub 上找到。

让我们来看看具体内容。

1.3 真正的模块

你的模块包是仓库的核心，不应该被隐藏起来:

如果你的模块只包含一个文件，你可以直接把它放在仓库的根目录下:

这个模块不应该属于任何一个模棱两可的 src 或者 python 子目录。

1.4 LICENSE

除了源代码本身以外，这毫无疑问是仓库中最重要的一部分。在这个文件中应该包含完整的许可说明和授权。

如果你不太清楚应该使用哪种许可证，请查看 choosealicense.com。

当然，你也可以在不做任何许可说明的情况下自由地发布代码，但这会阻碍许多潜在的想使用或贡献代码的用户。

1.5 Setup.py

如果你的模块包位于仓库的根目录，显然这个文件也应该在根目录下。

1.6 Requirements 文件

一个 pip requirements 文件应该放在仓库的根目录。它应该指明为项目做贡献时所需的依赖: 测试,、构建和生成文档。

如果你的项目没有任何开发依赖，或者你更喜欢通过 setup.py 来设置开发环境，那么这个文件不是必须的。

1.7 文档

没有任何理由把它放到其他地方。

1.8 测试套件

想了解关于编写测试的建议，请阅读《测试你的代码》。

最开始，一个小的测试套件经常存放在一个文件中:

随着测试套件的数量逐渐增加，你可以将它放到文件夹中，如下所示：

当然，这些测试模块需要导入你的包来进行测试，有以下几种方式：

• 将你的包安装到 site-packages 目录中
• 简单直接地修改路径

我强烈推荐使用后者。如果要求开发者使用 setup.py develop 来测试一个经常更新的代码库，需要他们为每一个版本的代码库设置一个独立的测试环境，这将非常麻烦。

为了给单个测试导入上下文，创建 tests/context.py 文件：

然后，在每一个测试模块中，如下所示导入：

这样就能够按预期工作，而不用采用安装的方式。

有些人会说应该把你的测试用例放到你的模块中——我不同意。这样会增加用户使用的复杂度，而且许多测试套件通常需要额外的依赖项和运行时上下文。

1.9 Makefile

如果你看过我的项目或者其他开源项目，你会发现都有一个 Makefile。为什么？这些项目也不是用 C 语言写的......简而言之，对于定义常规的管理任务，make 是非常有用的工具。

Makefile 示例：

其他的常规管理脚本（如 manage.py 或 fabfile.py），也放在仓库的根目录下。

1.10 关于 Django 应用程序

从 Django 1.4 开始，我注意到 Django 应用程序中的一个新趋势。很多开发者错误地使用Django 自带的应用模板创建项目，导致他们的仓库结构非常糟糕。

怎么会这样? 是的, 他们在创建一个新的仓库后，通常都这样操作：

最终生成的仓库结构是这样的：

请不要这样做。

重复的路径会让工具和开发者都很疑惑。没有必要的嵌套对任何人都没有好处（除非他们怀念庞大的 SVN 仓库）。

让我们这样来做：

注意末尾的“.”，指定在当前目录下创建项目目录结构。

最终的结构是这样的：

2 代码结构是关键

得益于 Python 提供的导入与处理模块的方式，结构化 Python 项目变得相对简单。这里说的简单，指的是你没有太多约束限制，而且模块导入功能容易掌握。因此，你只剩下单纯的架构性工作：设计、实现项目的不同模块，并梳理它们之间的交互关系。

容易结构化的项目同样意味着它的结构化容易做得糟糕。糟糕的项目结构包括以下特征：

• 多重且混乱的循环依赖关系：假如 furn.py 中的 Table 与 Chair 类需要导入 workers.py 中的 Carpenter 类来回答类似 table.isdoneby() 的问题，并且 Carpenter 类需要引入 Table 和 Chair 类以回答 carpenter.whatdo() 这类问题，此时就产生了循环依赖。在这种情况下，你不得不借助一些不太靠谱的小技巧，如在方法或函数内部使用 import 语句。
• 隐藏耦合：Table 类代码每次变更都会破坏20个不相关的测试用例，因为它影响了 Carpenter 类的代码，这要求谨慎地维护以适应变更。这种情况意味着 Carpenter 类代码与 Table 类之间存在较强的耦合性。
• 大量使用全局变量或上下文：如果 Table 和 Carpenter 类使用既能被直接修改又能被不同引用修改的全局变量，而不是直接传递（height，width，type，wood）变量。就需要仔细检查全局变量的所有入口，来理解为什么一个长方形桌子变成了正方形，最后发现远程模板代码也修改了这份上下文，扰乱了桌子尺寸的定义。
• 面条式代码：多页嵌套的 if 语句与 for 循环，包含大量复制粘贴的过程代码，且没有适当的分割，这样的代码被称为面条式代码。Python 中有意义的缩进（最具争议的特性之一）使面条式代码很难维持。因此，好消息是你也许不会经常看到面条式代码。
• Python中更可能出现混沌代码：这类代码包含上百段相似的逻辑碎片，通常是缺乏合适结构的类或对象。如果你始终弄不清手头上的任务应该使用 FurnitureTable，AssetTable还是 Table，甚至 TableNew，也许你已经陷入了混沌代码中。

3 模块

Python 模块是最主要的抽象层之一，并且很可能是最自然的一个。抽象层允许将代码分为不同部分，存放相关的数据与功能。

例如，在项目中，一层控制用户操作相关接口，另一层处理底层数据操作。划分这两层最自然的方式是，封装所有功能接口到一个文件，并将所有底层操作封装到另一个文件

剩余内容已隐藏，支付完成后下载完整资料

英语原文共 11 页，剩余内容已隐藏，支付完成后下载完整资料

资料编号：[595971]，资料为PDF文档或Word文档，PDF文档可免费转换为Word