Python代码质量：工具和最佳实践

In this article, we’ll identify high-quality Python code and show you how to improve the quality of your own code.

在本文中，我们将识别高质量的Python代码，并向您展示如何提高自己的代码质量。

We’ll analyze and compare tools you can use to take your code to the next level. Whether you’ve been using Python for a while, or just beginning, you can benefit from the practices and tools talked about here.

我们将分析和比较可用于将代码提升到新水平的工具。 无论您是长期使用Python还是刚开始使用Python，都可以从这里讨论的实践和工具中受益。

什么是代码质量？ (What is Code Quality?)

Of course you want quality code, who wouldn’t? But to improve code quality, we have to define what it is.

当然，您需要质量代码，谁不会呢？ 但是为了提高代码质量，我们必须定义它的含义。

A quick Google search yields many results defining code quality. As it turns out, the term can mean many different things to people.

快速的Google搜索会产生许多定义代码质量的结果。 事实证明，该术语对人们可能意味着许多不同的东西。

One way of trying to define code quality is to look at one end of the spectrum: high-quality code. Hopefully, you can agree on the following high-quality code identifiers:

尝试定义代码质量的一种方法是查看频谱的一端：高质量代码。 希望您可以同意以下高质量代码标识符：

• It does what it is supposed to do.
• It does not contain defects or problems.
• It is easy to read, maintain, and extend.

• 它完成了应该做的事情。
• 它不包含缺陷或问题。
• 它易于阅读，维护和扩展。

These three identifiers, while simplistic, seem to be generally agreed upon. In an effort to expand these ideas further, let’s delve into why each one matters in the realm of software.

这三个标识符虽然很简单，但似乎已被普遍认可。 为了进一步扩展这些想法，让我们深入研究为什么每个问题在软件领域都很重要。

为什么代码质量很重要？ (Why Does Code Quality Matter?)

To determine why high-quality code is important, let’s revisit those identifiers. We’ll see what happens when code doesn’t meet them.

为了确定高质量代码为何如此重要，让我们重新访问这些标识符。 我们将看到代码不符合要求时会发生什么。

它没有做应该做的事 (It does not do what it is supposed to do)

Meeting requirements is the basis of any product, software or otherwise. We make software to do something. If in the end, it doesn’t do it… well it’s definitely not high quality. If it doesn’t meet basic requirements, it’s hard to even call it low quality.

满足要求是任何产品，软件或其他产品的基础。 我们制作软件来做某事。 如果最后还是没有做到……那绝对不是高质量。 如果不满足基本要求，就很难称其为低质量。

它确实包含缺陷和问题 (It does contain defects and problems)

If something you’re using has issues or causes you problems, you probably wouldn’t call it high-quality. In fact, if it’s bad enough, you may stop using it altogether.

如果您使用的东西有问题或导致问题，您可能不会称其为高质量。 实际上，如果它足够糟糕，您可能会完全停止使用它。

For the sake of not using software as an example, let’s say your vacuum works great on regular carpet. It cleans up all the dust and cat hair. One fateful night the cat knocks over a plant, spilling dirt everywhere. When you try to use the vacuum to clean the pile of dirt, it breaks, spewing the dirt everywhere.

为了不使用软件作为示例，假设您的吸尘器在普通地毯上效果很好。 它可以清除所有灰尘和猫毛。 命运的一个夜晚，猫把植物撞倒，到处都是泥土。 当您尝试使用真空吸尘器清洁一堆污垢时，它会破裂，将污垢喷到各处。

While the vacuum worked under some circumstances, it didn’t efficiently handle the occasional extra load. Thus, you wouldn’t call it a high-quality vacuum cleaner.

尽管真空在某些情况下仍然有效，但它并不能有效地处理偶尔的额外负载。 因此，您不会称其为高质量的真空吸尘器。

That is a problem we want to avoid in our code. If things break on edge cases and defects cause unwanted behavior, we don’t have a high-quality product.

我们要在代码中避免这个问题。 如果情况突然恶化并且缺陷导致不良行为，我们将没有高质量的产品。

难以阅读，维护或扩展 (It is difficult to read, maintain, or extend)

Imagine this: a customer requests a new feature. The person who wrote the original code is gone. The person who has replaced them now has to make sense of the code that’s already there. That person is you.

想象一下：客户请求一项新功能。 编写原始代码的人不见了。 现在，替换它们的人必须了解已经存在的代码。 那个人就是你

If the code is easy to comprehend, you’ll be able to analyze the problem and come up with a solution much quicker. If the code is complex and convoluted, you’ll probably take longer and possibly make some wrong assumptions.

如果代码易于理解，您将能够分析问题并更快地提出解决方案。 如果代码复杂且令人费解，则可能需要花费更长的时间，并可能做出一些错误的假设。

It’s also nice if it’s easy to add the new feature without disrupting previous features. If the code is not easy to extend, your new feature could break other things.

如果很容易添加新功能而又不破坏以前的功能，那也很好。 如果代码不容易扩展，那么您的新功能可能会破坏其他功能。

No one wants to be in the position where they have to read, maintain, or extend low-quality code. It means more headaches and more work for everyone.

没有人愿意站在必须阅读，维护或扩展低质量代码的位置。 这意味着每个人都有更多的头痛和更多的工作。

It’s bad enough that you have to deal with low-quality code, but don’t put someone else in the same situation. You can improve the quality of code that you write.

您必须处理低质量的代码，但又不要让其他人处于同样的境地，这已经很糟糕了。 您可以提高所编写代码的质量。

If you work with a team of developers, you can start putting into place methods to ensure better overall code quality. Assuming that you have their support, of course. You may have to win some people over (feel free to send them this article ).

如果与开发人员团队合作，则可以开始采用适当的方法来确保更好的整体代码质量。 当然，假设您有他们的支持。 您可能需要赢得一些人的支持（请随时向他们发送本文）。

如何提高Python代码质量 (How to Improve Python Code Quality)

There are a few things to consider on our journey for high-quality code. First, this journey is not one of pure objectivity. There are some strong feelings of what high-quality code looks like.

在使用高质量代码的过程中，需要考虑一些事项。 首先，这一旅程不是纯粹的客观性之一。 对高质量代码的外观有一些强烈的感觉。

While everyone can hopefully agree on the identifiers mentioned above, the way they get achieved is a subjective road. The most opinionated topics usually come up when you talk about achieving readability, maintenance, and extensibility.

尽管每个人都可以希望就上述标识符达成共识，但是实现它们的方法是主观的。 当您谈论实现可读性，维护性和可扩展性时，最自以为是的话题通常会出现。

So keep in mind that while this article will try to stay objective throughout, there is a very-opinionated world out there when it comes to code.

因此，请记住，尽管本文将始终保持客观性，但在代码方面还是有一个很好的建议。

So, let’s start with the most opinionated topic: code style.

因此，让我们从最自以为是的主题开始：代码样式。

风格指南 (Style Guides)

Ah, yes. The age-old question: spaces or tabs?

是的。 古老的问题： 空格或制表符 ？

Regardless of your personal view on how to represent whitespace, it’s safe to assume that you at least want consistency in code.

无论您对如何表示空白有什么个人看法，都可以安全地假设您至少想要代码的一致性。

A style guide serves the purpose of defining a consistent way to write your code. Typically this is all cosmetic, meaning it doesn’t change the logical outcome of the code. Although, some stylistic choices do avoid common logical mistakes.

样式指南的目的是定义一致的代码编写方式。 通常，这些都是修饰性的，这意味着它不会改变代码的逻辑结果。 虽然，某些样式选择确实避免了常见的逻辑错误。

Style guides serve to help facilitate the goal of making code easy to read, maintain, and extend.

样式指南有助于实现使代码易于阅读，维护和扩展的目标。

As far as Python goes, there is a well-accepted standard. It was written, in part, by the author of the Python programming language itself.

就Python而言，有一个公认的标准。 它部分是由Python编程语言本身的作者编写的。

PEP 8 provides coding conventions for Python code. It is fairly common for Python code to follow this style guide. It’s a great place to start since it’s already well-defined.

PEP 8提供了Python代码的编码约定。 Python代码遵循此样式指南非常普遍。 这是一个很好的起点，因为它已经明确定义。

A sister Python Enhancement Proposal, PEP 257 describes conventions for Python’s docstrings, which are strings intended to document modules, classes, functions, and methods. As an added bonus, if docstrings are consistent, there are tools capable of generating documentation directly from the code.

PEP 257是一个姊妹的Python增强建议，描述了Python文档字符串的约定，这些文档字符串旨在记录模块，类，函数和方法。 另外，如果文档字符串一致，则有一些工具可以直接从代码生成文档。

All these guides do is define a way to style code. But how do you enforce it? And what about defects and problems in the code, how can you detect those? That’s where linters