Python 编码规范 PEP8

1 Introduction

---

Guido 的核心思想是：对于代码而言，相比于写，它更多是被用来读的。这个指导旨在使Python代码更易读，且具有更强的协调性。

2 A Foolish Consistency is the Hobgoblin of Little Minds

---

然而有些情况下遵从guide不是很合适，要学会变通，查看其他人的代码，并且不要害怕提问

当遵从guideline的是会降低可读性、降低继承性/可移植性、使得代码无法与环境中其他代码兼容、需要和其他不符合这个guide的其他python版本代码兼容的时候，记得变通。

3 Code lay-out

---

·使用四个空格缩进，python3不兼容tab与空格混用；

·每行不超过80个字符。为了保证代码段可以自由左右移动，建议一行不超过72个字符。有些团队会有大于80的行字符限制，但是注释仍然应保持在72字符以内

·长的行需要换行的时候，使用Python自动连接括号（或者方括号、花括号）内的内容的功能，不要使用强制换行符。换行的时候注意内容的垂直对齐，增加一级缩进以防歧义或识别不明。在不能使用空格的时候才用\换行

·当if的条件很复杂的时候，在使用 “if (...”的形式可以形成自然的四格缩进，会导致歧义；有以下的解决方案——增加一行注释来区分内容和条件；增加多是缩进来区分内容和条件

·多行内容结束时，右括号可以放在最后一行内容第一个字符的正下方或者是开始这个多行语句的正下方。

·在二元操作符之前换行会使代码更整齐

·在class和一级函数上用两个空行，类内的函数使用一个空行，可以用多的空行来区分不同块的函数，简单的程序间可以省略空行

·应该使用UTF-8（python3）或ASCII（python2）编码，按此规范编码的程序不需要声明。非标准编码方式应该只在测试需要的情况或者注释中使用。

·在python3及以上的版本中，只使用ASCII编码字符作为标识符（identifiers），并且尽量使用英文词汇作为标识符。除了1）测试集中含有非ASCII字符，2）作者的姓名（不基于拉丁语系的字母必须给出拉丁文翻译），这两个情况之外，字符串和注释也必须使用ASCII字符。

·import的时候不同的库分开引用，但是可以将从同一个库中引用的模块合并写。总是在文件开头就进行引用——在注释、文件信息之后，全局模块、常量之前。

·import应按照以下顺序分组（用空行隔开组）：1）标准库，2）相关的第三方库，3）本地的库或特殊引用

·建议精确引用以提升可读性、稳定性。除非精确引用会导致本地变量名的冲突。避免在引用时使用通配符*

·模块级别的“dunders”（例如__all__,__author__等）应该放在文件头说明之后、引用之前。这个类型的赋值也应放在import之前。

4 String Quotes

---

固定一种字符串的符号，并在内容中出现歧义的时候用另外一种代替，避免使用\符号以增加可读性。

5 Whitespace in Expressions and Statements

---

·括号两侧、冒号，分号之前、’不用空格

·关于切片的空格没看懂，大体是要统一、可以看作二元操作符

·总是在 =（赋值）， += ，-=，==，<，>，！=，<=，>=，in,not in, is,is not, and or not，->等二元操作符两侧加空格

·当有多级优先级运算的时候，在最低级的操作符两侧加空格

·在=表示变量默认值的时候 不用加空格

·不要在同一行里做多个操作

6 When to use trailing commas

---

https://www.python.org/dev/peps/pep-0008/#id29

7 Comments

---

·注释应该是完整的句子，并且保证句首大写（除非句首是个小写的变量名），长句子要在句尾加句号，在句尾句号之后用两个空格隔开。

·注释块：和被注释的对象统一缩进等级。每一行以“# ”开头，边缘用一行“#”表示

·行内注释：至少要空开两格再开始写，同样以“# ”开头

·文档的注释串：为所有public的模块、函数、类、methods写注释。不是所有非public都要有注释，但是你应该为它写一个评论来说明功能，在def下面一行。注意，多行的注释结束时的”””应该另起一行

8 Naming Conventions

---

python 的library是混乱的，所以永远不能指望这部分能完全一致，下面有些推荐的命名标准。新写的包应该遵循以下标准，已经写好的就不管了。

overriding principle：使用当前API时可见的变量名应该反应其作用

Descriptive--Naming Styles：

保持统一的风格

使用首字母大写的时候，缩写单词要全大写——HTTPSeverError

不要自己发明这样形式的名字：__haha__

Prescriptive--Name Conventions：

·不要使用小写l，大写O，大写I作为单个字母变量名

·应该使用标准ASCLII编码字符作为变量名

·module:短的、全小写的名字。可以用下划线增加可读性，但是不鼓励。当C或C++模块是更高级的时候，在开头加一个下划线 标明

·Class：首字母大写格式CapWords，可以使用函数的命名约定来代替在借口被记录并主要用作可调用的情况。类内命名有多中形式——单个词或者两个词连着写，首字母大写的情况只用于exception和constants

·Type variables：首字母大写，并且简写。AnyStr，建议在covariant或vontravariant行为的时候使用“_co”,"_contra"后缀。例如：VT_co = TypeVar('VT_co', covariant=True)

·Exception:应该是类，所以用类的命名方式，但是应该加上“Error”后缀（如果是一个错误的话）

·Global Variable：假设只在一个模块里面用。具有 from M import * 功能的模块应该使用__all__机制来防止导出全局变量，或者使用之前的在前面加前缀的方式来防止这一点。

·Function：小写，单词用下划线隔开。混合形式只在之前使用过这样的形式里使用来保持与之前的兼容。

·Function and method argument：总是在第一次出现instance methods的argument时使用self；在第一次出现class methods 的 argument的时候使用cls。在出现和保留字冲突的时候，在单词后面加一个下划线比使用简写或者其他拼写更好。

·Method names and instance variables：使用function的命名规则——小写字母加下划线。仅在非public methods和instance variables的时候使用开头下划线。为了防止和子类的冲突，在开头使用双下划线来激活python的命名 mangling规则（使用Foo.__a无法调用，而应该使用Foo._Foo__a）

·Constants：通常是在模块里的常量，全大写、用下划线隔开：MAX_OVERFLOW，TOTAL

·总是确定methods 和instance variables 是否全局可用，不确定的时候用non-public。全局变量是在那些和当前类不相关的用户使用的。[这块后面还有好多，暂时用不到，以后看]

Public and internal interfaces

9 Programming Recommendations

---

·程序需要在其他平台也可用：不要依赖Cpy的字符串加法 而是用join

·None值的判定总是使用 is或者 is not 而不是使用等于操作，然后在bool变量的时候可能会有歧义——if x 表示 if x is not None

· 使用 is not 而不是 not ... is

·在 implement 比较顺序函数的时候，同时implement六个操作（__eq__,__ne__,__lt__,__le__,__gt__,__ge__）而不是仅包含部分操作符

·总是使用 def 而不是lambda表达式赋值来表示一个直接的函数

·Exception 和BaseException

·raise

·except

·system error

·try

·with

·保证函数要么所有情况都有返回值要么都没有

·使用string method 而不是string modulw

·使用 ''.startswith()和''.endswith()而不是string切片来检查前后缀，其他的比较应该用isinstance()而不是直接比较type()函数值

·在判断序列是否为空的时候，使用if seq ，而不是 if len(seq)

·不要依赖字符串结尾的空格

·不要用 True来判断boolean值：

　　yes：   if greeting

　　no:       if greeting == Ture

Worse: if greeting is True

·Function Annotations