Python3代码样式指导手册

代码布局

缩进

  • 每个缩进级别采用4个空格

  • 连续行所包装的元素应该要么使用Python隐式排列，即垂直对齐于圆括号，方括号花括号

  • 或者采用悬挂缩进，采用悬挂缩进需考虑第一行不应该包括参数，并且在续行中需要再缩进一级以清楚显示

  • 对于续行来说，4空格规则可以不遵守

  • 如果if语句太长，需要用到多行书写

  • 2个字符（例如if）加上一个空格和一个左括号刚好是4空格缩进，但这对多行条件语句的续行是没用的因为这会和if语句中嵌套的其他的缩进语句产生视觉上的冲突

  • 这份PEP中并没有做出明确的说明应该怎样来区分条件语句和if语句中所嵌套的语句

  • 多行结束右圆/方/花括号可以单独一行书写和上一行的缩进对齐

  • 也可以和多行开始的第一个字符对齐

Tab还是空格？

  • 推荐使用空格来进行缩进

  • tab应该只有在现有代码已经使用tab进行缩进的情况下使用以便和现有代码保持一致

  • python3不允许tab和空格共同使用

每行最大长度

  • 将所有行都限制在79个长度以内

  • 对于连续大段的文字（比如文档字符串（docstring）或注释），其结构上的限制更少这些行应该被限制在72个字符长度之内

  • 调整窗口宽度能让多个文件同时打开在屏幕上显示，在使用代码评审（code review）工具时在两个相邻窗口显示两个版本的代码会更好

  • 很多工具默认自动换行会破坏代码结构，使代码变得难以理解

  • 在窗口大小为80个字符的编辑器中，在换行时，编辑器可能会在最后一列放置一个标记，为避免自动换行也需要限制酶行字符串的长度

  • 一些基于web的工具根本没有换行的可能

  • 一些团对会强烈希望行长度不止79个字符

  • 当代码仅仅是由一个团队维护时，达成一致后，可将长度改写成99个字符长度，注释和文档字符依然是72个字符

  • python标准库比较保守，要求将行长度限制在99个字符串内

  • 推荐的换行方式是利用 Python 圆括号、方括号和花括号中的隐式续行（implied line continuation）。

  •   很长的行可以通过在括号内换行来分成多行。  最好加上反斜杠来区别续行。  有时只能使用反斜杠。

  • 较长的多个 with 语句不能采用隐式续行，只能接受反斜杠表示换行：

二元运算符之前还是之后换行？

  • 一直以来推荐的风格是在二元运算符之后换行。 

  • 但是有两方面可以说明这会破坏代码的可读性： 

    1. 在屏幕上运算符会分散在不同列上

    1. 运算符会留在上一行而远离操作数 

  • 所以，阅读代码的时候眼睛要紧盯来确定哪些操作数被加，哪些操作数被减

空行

  • 使用 2 个空行来分隔最外层的函数（function）和类（class）定义。

  • 使用 1 个空行来分隔类中的方法（method）定义。

  • 可以使用额外的空行（尽量少）来分隔一组相关的函数。

  • 在一系列相关的仅占一行的函数之间，空行也可以被省略（比如一组虚函数定义）。

  • 在函数内使用空行（尽量少）使代码逻辑更清晰。

  • Python 支持 control-L（如:^L） 换页符作为空格；

  • 许多工具将这些符号作为分页符，因此可以使用这些符号来分页或者区分文件中的相关区域。

  • 注意，一些编辑器和基于 web 的代码预览器可能不会将 control-L 识别为分页符，而是显示成其他符号。

源文件编码

  • Python 关键发行版中的代码应该一直使用 UTF-8（Python2 中使用 ASCII）。

  • 使用 ASCII（Python2）或者UTF-8（Python3）的文件不应该添加编码声明。

  • 在标准库中，那些用作测试的代码，注释，文档字符串需要提及作者名字而不得不使用非ASCII字符时，才能使用非默认的编码。

    • 否则，在字符串文字中包括非 ASCII 数据时，推荐使用 \x ， \u ， \U 或 \N 等转义符

    • 此外，字符串文字和注释应该只包括 ASCII 编码。

      只有两种例外：

      • 测试情况下为了测试非ASCII编码的特性

      • 作者名字。作者名字不是由拉丁字母组成的也必须提供一个拉丁音译名。


      鼓励具有全球受众的开放源码项目采用类似的原则。