PEP 8 – Style Guide for Python Code (Introduction; A Foolish Consistency is the Hobgoblin of Little Minds)

Introduction引言#

This document gives coding conventions for the Python code comprising the standard library in the main Python distribution. Please see the companion informational PEP describing style guidelines for the C code in the C implementation of Python.

本文档为构成 Python 主发行版标准库的 Python 代码给出编码约定。关于 Python 的 C 语言实现中 C 代码的风格准则，请参阅与之配套的信息类 PEP。

This document and PEP 257 (Docstring Conventions) were adapted from Guido’s original Python Style Guide essay, with some additions from Barry’s style guide.

本文档与 PEP 257（文档字符串约定）改编自 Guido 最初的那篇《Python 风格指南》短文，并吸收了 Barry 的风格指南中的一些内容。

This style guide evolves over time as additional conventions are identified and past conventions are rendered obsolete by changes in the language itself.

随着新的约定被总结出来、旧的约定因语言本身的变化而过时，这份风格指南也在不断演进。

Many projects have their own coding style guidelines. In the event of any conflicts, such project-specific guides take precedence for that project.

许多项目有自己的编码风格准则。如有冲突，以该项目自己的准则为准。

A Foolish Consistency is the Hobgoblin of Little Minds愚蠢的一致性是狭隘心灵的妖怪#

One of Guido’s key insights is that code is read much more often than it is written. The guidelines provided here are intended to improve the readability of code and make it consistent across the wide spectrum of Python code. As PEP 20 says, “Readability counts”.

Guido 的一个关键洞见是：代码被阅读的次数远多于被编写的次数。这里给出的准则，旨在提高代码的可读性，并让形形色色的 Python 代码保持一致。正如 PEP 20 所说：“可读性很重要。”

A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is the most important.

风格指南关乎一致性。与本指南保持一致很重要；在一个项目之内保持一致更重要；在一个模块或函数之内保持一致最重要。

However, know when to be inconsistent – sometimes style guide recommendations just aren’t applicable. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don’t hesitate to ask!

然而，要懂得什么时候不必一致——有时风格指南的建议就是不适用。拿不准的时候，运用你自己最好的判断。看看别的例子，决定怎样最好看。也别犹豫，开口问吧！

In particular: do not break backwards compatibility just to comply with this PEP!

尤其是：不要仅仅为了符合本 PEP 而破坏向后兼容！

Some other good reasons to ignore a particular guideline:

忽略某条准则的其他正当理由还有：

1. When applying the guideline would make the code less readable, even for someone who is used to reading code that follows this PEP.

1. 应用这条准则会让代码更难读，哪怕对一个习惯了遵循本 PEP 的代码的人来说也是如此。

2. To be consistent with surrounding code that also breaks it (maybe for historic reasons) – although this is also an opportunity to clean up someone else’s mess (in true XP style).

2. 为了与周围同样违反这条准则的代码保持一致（也许出于历史原因）——不过这也是一个替别人收拾烂摊子的机会（正宗的 XP 风格）。

3. Because the code in question predates the introduction of the guideline and there is no other reason to be modifying that code.

3. 相关代码早于这条准则出现，而且也没有别的理由去修改那段代码。

4. When the code needs to remain compatible with older versions of Python that don’t support the feature recommended by the style guide.

4. 代码需要兼容较老版本的 Python，而那些版本不支持风格指南所推荐的特性。