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

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

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.

## 什么是代码质量？(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.

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.

### 风格指南(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.

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 come in.

### 短绒(Linters)

#### 什么是短绒棉？(What is a Linter?)

First, let’s talk about lint. Those tiny, annoying little defects that somehow get all over your clothes. Clothes look and feel much better without all that lint. Your code is no different. Little mistakes, stylistic inconsistencies, and dangerous logic don’t make your code feel great.

But we all make mistakes. You can’t expect yourself to always catch them in time. Mistyped variable names, forgetting a closing bracket, incorrect tabbing in Python, calling a function with the wrong number of arguments, the list goes on and on. Linters help to identify those problem areas.

Additionally, most editors and IDE’s have the ability to run linters in the background as you type. This results in an environment capable of highlighting, underlining, or otherwise identifying problem areas in the code before you run it. It is like an advanced spell-check for code. It underlines issues in squiggly red lines much like your favorite word processor does.

Linters analyze code to detect various categories of lint. Those categories can be broadly defined as the following:

1. Logical Lint
• Code errors
• Code with potentially unintended results
• Dangerous code patterns
2. Stylistic Lint
• Code not conforming to defined conventions
1. 逻辑皮棉
• 代码错误
• 可能产生意外结果的代码
• 危险代码模式
2. 文体皮棉
• 代码不符合定义的约定

There are also code analysis tools that provide other insights into your code. While maybe not linters by definition, these tools are usually used side-by-side with linters. They too hope to improve the quality of the code.

Finally, there are tools that automatically format code to some specification. These automated tools ensure that our inferior human minds don’t mess up conventions.

#### 我的Python Linter选项有哪些？(What Are My Linter Options For Python?)

Before delving into your options, it’s important to recognize that some “linters” are just multiple linters packaged nicely together. Some popular examples of those combo-linters are the following:

Flake8: Capable of detecting both logical and stylistic lint. It adds the style and complexity checks of pycodestyle to the logical lint detection of PyFlakes. It combines the following linters:

Flake8 ：能够检测逻辑和样式棉绒。 它将pycodestyle的样式和复杂性检查添加到PyFlakes的逻辑皮棉检测中。 它结合了以下短毛绒：

• PyFlakes
• pycodestyle (formerly pep8)
• Mccabe
• PyFlakes
• pycodestyle（以前为pep8）
• 麦卡比

Pylama: A code audit tool composed of a large number of linters and other tools for analyzing code. It combines the following:

Pylama ：一种代码审核工具，由大量短绒和其他用于分析代码的工具组成。 它结合了以下内容：

• pycodestyle (formerly pep8)
• pydocstyle (formerly pep257)
• PyFlakes
• Mccabe
• Pylint
• gjslint
• pycodestyle（以前为pep8）
• pydocstyle（以前是pep257）
• PyFlakes
• 麦卡比
• 皮林特
• gjslint

Here are some stand-alone linters categorized with brief descriptions:

Linter 林特 Category 类别 Description 描述
Pylint皮林特 Logical & Stylistic 逻辑和文体 Checks for errors, tries to enforce a coding standard, looks for code smells 检查错误，尝试执行编码标准，查找代码气味
PyFlakesPyFlakes Logical 逻辑上 Analyzes programs and detects various errors 分析程序并检测各种错误
pycodestylepycodestyle Stylistic 文体 Checks against some of the style conventions in PEP 8 检查PEP 8中的某些样式约定
pydocstylepydocstyle Stylistic 文体 Checks compliance with Python docstring conventions 检查是否符合Python文档字符串约定
Bandit土匪 Logical 逻辑上 Analyzes code to find common security issues 分析代码以查找常见的安全问题
MyPyMyPy Logical 逻辑上 Checks for optionally-enforced static types 检查强制执行的静态类型

And here are some code analysis and formatting tools:

Tool 工具 Category 类别 Description 描述
Mccabe麦卡比 Analytical 分析型 McCabe complexityMcCabe的复杂性
Radon Analytical 分析型 Analyzes code for various metrics (lines of code, complexity, and so on) 分析各种指标的代码（代码行，复杂度等）
Black黑色 Formatter 格式化程序 Formats Python code without compromise 毫不妥协地格式化Python代码
IsortIsort Formatter 格式化程序 Formats imports by sorting alphabetically and separating into sections 通过按字母顺序排序并分成几部分来格式化导入

#### 比较Python Linter(Comparing Python Linters)

Let’s get a better idea of what different linters are capable of catching and what the output looks like. To do this, I ran the same code through a handful of different linters with the default settings.

The code I ran through the linters is below. It contains various logical and stylistic issues:

 """
"""
code_with_lint.py
code_with_lint.py
Example Code with lots of lint!
Example Code with lots of lint!
"""
"""
import import io
io
from from math math import import *

*

from from time time import import time

time

some_global_var some_global_var = = 'GLOBAL VAR NAMES SHOULD BE IN ALL_CAPS_WITH_UNDERSCOES'

'GLOBAL VAR NAMES SHOULD BE IN ALL_CAPS_WITH_UNDERSCOES'

def def multiplymultiply (( xx , , yy ):
):
"""
"""
This returns the result of a multiplation of the inputs
This returns the result of a multiplation of the inputs
"""
"""
some_global_var some_global_var = = 'this is actually a local variable...'
'this is actually a local variable...'
result result = = xx * * y
y
return return result
result
if if result result == == 777777 :
:
printprint (( "jackpot!""jackpot!" )

)

def def is_sum_luckyis_sum_lucky (( xx , , yy ):
):
"""This returns a string describing whether or not the sum of input is lucky
"""This returns a string describing whether or not the sum of input is lucky
This function first makes sure the inputs are valid and then calculates the
This function first makes sure the inputs are valid and then calculates the
sum. Then, it will determine a message to return based on whether or not
sum. Then, it will determine a message to return based on whether or not
that sum should be considered "lucky"
that sum should be considered "lucky"
"""
"""
if if x x != != NoneNone :
:
if if y y is is not not NoneNone :
:
result result = = xx ++ yy ;
;
if if result result == == 77 :
:
return return 'a lucky number!'
'a lucky number!'
elseelse :
:
returnreturn ( ( 'an unlucky number!''an unlucky number!' )

)

return return (( 'just a normal number''just a normal number' )

)

class class SomeClassSomeClass :

:

def def __init____init__ (( selfself , , some_argsome_arg ,  ,  some_other_argsome_other_arg , , verbose verbose = = FalseFalse ):
):
selfself .. some_other_arg  some_other_arg  =  =  some_other_arg
some_other_arg
selfself .. some_arg        some_arg        =  =  some_arg
some_arg
list_comprehension list_comprehension = = [(([(( 100100 // valuevalue )) ** pipi ) ) for for value value in in some_arg some_arg if if value value != != 00 ]
]
time time = = timetime ()
()
from from datetime datetime import import datetime
datetime
date_and_time date_and_time = = datetimedatetime .. nownow ()
()
return
return


The comparison below shows the linters I used and their runtime for analyzing the above file. I should point out that these aren’t all entirely comparable as they serve different purposes. PyFlakes, for example, does not identify stylistic errors like Pylint does.

Linter 林特 Command 命令 Time 时间
Pylint皮林特 pylint code_with_lint.py pylint code_with_lint.py 1.16s 1.16秒
PyFlakesPyFlakes pyflakes code_with_lint.py pyflakes code_with_lint.py 0.15s 0.15秒
pycodestylepycodestyle pycodestyle code_with_lint.py pycodestyle code_with_lint.py 0.14s 0.14秒
pydocstylepydocstyle pydocstyle code_with_lint.py pydocstyle code_with_lint.py 0.21s 0.21秒

For the outputs of each, see the sections below.

##### 皮林特 (Pylint)

Pylint is one of the oldest linters (circa 2006) and is still well-maintained. Some might call this software battle-hardened. It’s been around long enough that contributors have fixed most major bugs and the core features are well-developed.

The common complaints against Pylint are that it is slow, too verbose by default, and takes a lot of configuration to get it working the way you want. Slowness aside, the other complaints are somewhat of a double-edged sword. Verbosity can be because of thoroughness. Lots of configuration can mean lots of adaptability to your preferences.

Without further ado, the output after running Pylint against the lint-filled code from above:

Note that I’ve condensed this with ellipses for similar lines. It’s quite a bit to take in, but there is a lot of lint in this code.

Note that Pylint prefixes each of the problem areas with a R, C, W, E, or F, meaning:

• [R]efactor for a “good practice” metric violation
• [C]onvention for coding standard violation
• [W]arning for stylistic problems, or minor programming issues
• [E]rror for important programming issues (i.e. most probably bug)
• [F]atal for errors which prevented further processing
• [R]违反“良好做法”指标的因素
• [C]违反编码标准的发明
• [W]警告样式问题或次要编程问题
• [E]对于重要的编程问题（即很可能是错误）的错误
• [F]致命错误，导致无法进一步处理

The above list is directly from Pylint’s user guide.

##### PyFlakes (PyFlakes)

Pyflakes “makes a simple promise: it will never complain about style, and it will try very, very hard to never emit false positives”. This means that Pyflakes won’t tell you about missing docstrings or argument names not conforming to a naming style. It focuses on logical code issues and potential errors.

Pyflakes“做出了一个简单的承诺：它永远不会抱怨风格，并且会非常非常努力地避免产生误报”。 这意味着Pyflakes不会告诉您缺少不符合命名样式的文档字符串或参数名称。 它着重于逻辑代码问题和潜在错误。

The benefit here is speed. PyFlakes runs in a fraction of the time Pylint takes.

Output after running against lint-filled code from above:

code_with_lint.py:5: 'io' imported but unused
code_with_lint.py:6: 'from math import *' used; unable to detect undefined names
code_with_lint.py:14: local variable 'some_global_var' is assigned to but never used
code_with_lint.py:36: 'pi' may be undefined, or defined from star imports: math
code_with_lint.py:36: local variable 'list_comprehension' is assigned to but never used
code_with_lint.py:37: local variable 'time' (defined in enclosing scope on line 9) referenced before assignment
code_with_lint.py:37: local variable 'time' is assigned to but never used
code_with_lint.py:39: local variable 'date_and_time' is assigned to but never used
code_with_lint.py:5: 'io' imported but unused
code_with_lint.py:6: 'from math import *' used; unable to detect undefined names
code_with_lint.py:14: local variable 'some_global_var' is assigned to but never used
code_with_lint.py:36: 'pi' may be undefined, or defined from star imports: math
code_with_lint.py:36: local variable 'list_comprehension' is assigned to but never used
code_with_lint.py:37: local variable 'time' (defined in enclosing scope on line 9) referenced before assignment
code_with_lint.py:37: local variable 'time' is assigned to but never used
code_with_lint.py:39: local variable 'date_and_time' is assigned to but never used


The downside here is that parsing this output may be a bit more difficult. The various issues and errors are not labeled or organized by type. Depending on how you use this, that may not be a problem at all.

##### pycodestyle（以前为pep8） (pycodestyle (formerly pep8))

Used to check some style conventions from PEP8. Naming conventions are not checked and neither are docstrings. The errors and warnings it does catch are categorized in this table.

Output after running against lint-filled code from above:

The nice thing about this output is that the lint is labeled by category. You can choose to ignore certain errors if you don’t care to adhere to a specific convention as well.

##### pydocstyle（以前是pep257） (pydocstyle (formerly pep257))

Very similar to pycodestyle, except instead of checking against PEP8 code style conventions, it checks docstrings against conventions from PEP257.

Output after running against lint-filled code from above:

code_with_lint.py:1 at module level:
D200: One-line docstring should fit on one line with quotes (found 3)
code_with_lint.py:1 at module level:
D400: First line should end with a period (not '!')
code_with_lint.py:13 in public function multiply:
D103: Missing docstring in public function
code_with_lint.py:20 in public function is_sum_lucky:
D103: Missing docstring in public function
code_with_lint.py:31 in public class SomeClass:
D101: Missing docstring in public class
code_with_lint.py:33 in public method __init__:
D107: Missing docstring in __init__
code_with_lint.py:1 at module level:
D200: One-line docstring should fit on one line with quotes (found 3)
code_with_lint.py:1 at module level:
D400: First line should end with a period (not '!')
code_with_lint.py:13 in public function multiply:
D103: Missing docstring in public function
code_with_lint.py:20 in public function is_sum_lucky:
D103: Missing docstring in public function
code_with_lint.py:31 in public class SomeClass:
D101: Missing docstring in public class
code_with_lint.py:33 in public method __init__:
D107: Missing docstring in __init__


Again, like pycodestyle, pydocstyle labels and categorizes the various errors it finds. And the list doesn’t conflict with anything from pycodestyle since all the errors are prefixed with a D for docstring. A list of those errors can be found here.

##### 代码无毛 (Code Without Lint)

You can adjust the previously lint-filled code based on the linter’s output and you’ll end up with something like the following:

That code is lint-free according to the linters above. While the logic itself is mostly nonsensical, you can see that at a minimum, consistency is enforced.

In the above case, we ran linters after writing all the code. However, that’s not the only way to go about checking code quality.

## 什么时候可以检查代码质量？(When Can I Check My Code Quality?)

You can check your code’s quality:

• As you write it
• When it’s checked in
• When you’re running your tests
• 当你写的时候
• 签入时
• 运行测试时

It’s useful to have linters run against your code frequently. If automation and consistency aren’t there, it’s easy for a large team or project to lose sight of the goal and start creating lower quality code. It happens slowly, of course. Some poorly written logic or maybe some code with formatting that doesn’t match the neighboring code. Over time, all that lint piles up. Eventually, you can get stuck with something that’s buggy, hard to read, hard to fix, and a pain to maintain.

To avoid that, check code quality often!

### 当你写(As You Write)

You can use linters as you write code, but configuring your environment to do so may take some extra work. It’s generally a matter of finding the plugin for your IDE or editor of choice. In fact, most IDEs will already have linters built in.

Here’s some general info on Python linting for various editors:

### 签入代码之前(Before You Check In Code)

If you’re using Git, Git hooks can be set up to run your linters before committing. Other version control systems have similar methods to run scripts before or after some action in the system. You can use these methods to block any new code that doesn’t meet quality standards.

While this may seem drastic, forcing every bit of code through a screening for lint is an important step towards ensuring continued quality. Automating that screening at the front gate to your code may be the best way to avoid lint-filled code.

### 运行测试时(When Running Tests)

You can also place linters directly into whatever system you may use for continuous integration. The linters can be set up to fail the build if the code doesn’t meet quality standards.

Again, this may seem like a drastic step, especially if there are already lots of linter errors in the existing code. To combat this, some continuous integration systems will allow you the option of only failing the build if the new code increases the number of linter errors that were already present. That way you can start improving quality without doing a whole rewrite of your existing code base.

## 结论(Conclusion)

High-quality code does what it’s supposed to do without breaking. It is easy to read, maintain, and extend. It functions without problems or defects and is written so that it’s easy for the next person to work with.

Hopefully it goes without saying that you should strive to have such high-quality code. Luckily, there are methods and tools to help improve code quality.

Style guides will bring consistency to your code. PEP8 is a great starting point for Python. Linters will help you identify problem areas and inconsistencies. You can use linters throughout the development process, even automating them to flag lint-filled code before it gets too far.

Having linters complain about style also avoids the need for style discussions during code reviews. Some people may find it easier to receive candid feedback from these tools instead of a team member. Additionally, some team members may not want to “nitpick” style during code reviews. Linters avoid the politics, save time, and complain about any inconsistency.

In addition, all the linters mentioned in this article have various command line options and configurations that let you tailor the tool to your liking. You can be as strict or as loose as you want, which is an important thing to realize.

Improving code quality is a process. You can take steps towards improving it without completely disallowing all nonconformant code. Awareness is a great first step. It just takes a person, like you, to first realize how important high-quality code is.

• 0
点赞
• 0
评论
• 2
收藏
• 扫一扫，分享海报

09-28 4507
01-18 4378
09-06 9540
08-02 1020
04-10 1836
07-31 4556