Detailed introduction to Python coding format (with examples)

This article brings you a detailed introduction to Python coding format (with examples). It has certain reference value. Friends in need can refer to it. I hope it will be helpful to you.

The code is not only used for running, but also for reading. In order to make the code more readable, many programming languages ​​​​have their own coding standards. Specifications are developed to maintain code consistency to make the code more beautiful and readable. How the code should be formatted and written is not absolute, so some areas will be controversial. Sometimes style guides don’t apply, and the most important thing is to know when to be inconsistent. When you are unsure of what to do, you should look to other examples.

This article is only a reference for Python coding style, not a rule that must be done this way. The purpose of this article should be to serve as a guide to guide developers to write more readable code.

1. Code layout

Mainly the layout of indentation and blank lines:

• 1. Use 4 spaces To indent (any editor can accomplish this function), tab characters are not recommended, and tab characters and spaces cannot be mixed.

• 2. Each line should not exceed 80 characters. You can use backslashes for line breaks, and it is best to use brackets (Python will implicitly connected).

• 3. There are two blank lines between the class and the top-level function definition; one blank line between the method definitions in the class; one blank line between logically irrelevant paragraphs within the function; try not to repeat it elsewhere. Blank line.

Mainly the layout of the entire source code file:

• 1. The order of module content: module description, module documentation string, Import statements, global variables or constants, and other definitions.

• 2. The order of module import parts: standard library, third-party module, custom module; there is a blank line between each part.

• 3. Do not import multiple modules at one time in one import statement, such as import os, sys is not recommended.

• 4. When importing modules, you should use appropriate methods to avoid naming conflicts. For example, use from xx import xx only when appropriate, and try to avoid using ##. #from xx imoprt *.

• 5. In a self-written module, if you need to use

  from xx import *, you should use __all__# after the import statement or at the end of the module. ## Mechanism to restrict import rules.

3. Statement arrangement

1. Usually each statement should be on its own line.
2. Do not add a semicolon at the end of the line, and do not use semicolons to put multiple statements on the same line.
3. In the if/for/while statement, even if there is only one execution statement, try to start a new line.
4. Do not use parentheses in return statements (return) or conditional statements (if/for/while) unless they are used to implement row connections.
5. For if statements, when there is no else and the statement is relatively short, it can be completed in one line (but not recommended), for example:
• if foo: bar(foo)

  .

6. For simple class definition, it can also be completed in one line (but not recommended), such as defining an exception:
• class UnfoundError(Exception): pass

  .

7. Use vertical implicit indentation or use hanging indentation in parentheses for functions and methods.

• # 一行写不下时，有括号来连接多行，后续行应该使用悬挂缩进
  if (this_is_one_thing
          and that_is_another_thing):
      do_something()
  
  # 函数调用参数较多时，对准左括号
  f = foo(a, b,
          c, d)
  
  # 不对准左括号，但加多一层缩进，以和后面内容区别
  def long_function_name(
          a, b, c,
          d, e):
      print(a, b, c, d, e)
  
  # 列表、元组、字典以及函数调用时可以让右括号回退，这样更加美观
  l = [
      1, 2, 3,
      4, 5, 6,
  ]
  
  result = some_function(
      'a', 'b', 'c',
      'd', 'e', 'f',
  )

4. Use the general principle of

for spaces and avoid unnecessary spaces.

1. Do not add spaces before various right brackets.
2. Do not add spaces before commas, colons, and semicolons, but they should be added after them (except at the end of the line).
3. Do not add a space before the left bracket of the function. Such as Func(1).
4. Do not add a space before the left bracket of the sequence. Such as list[2].
5. Add a space to the left and right of the operator. Do not add spaces for alignment.
6. Omit spaces around the assignment characters used by the default parameters of the function.
Good style:

spam(ham[1], {eggs: 2})

if x == 4:
    print x, y; x, y = y, x

f = foo(1, 2, 3)

ham[1:9], ham[1:9:3], ham[:9:3], ham[1::3], ham[1:9:]
ham[lower:upper], ham[lower:upper:], ham[lower::step]
ham[lower+offset : upper+offset]
ham[: upper_fn(x) : step_fn(x)], ham[:: step_fn(x)]
ham[lower + offset : upper + offset]

x = 1
y = 2
long_variable = 3

def foo(a, b, c=0):
    return moo(m=a, n=b, o=c)

Bad style:

spam( ham[ 1 ], { eggs: 2 } )

if x == 4 :
    print x , y ; x , y = y , x

f = foo (1, 2, 3)

ham[lower + offset:upper + offset]
ham[1: 9], ham[1 :9], ham[1:9 :3]
ham[lower : : upper]
ham[ : upper]

x             = 1
y             = 2
long_variable = 3

def foo(a, b, c = 0):
    return moo(m = a, n = b, o = c)

5. Comments

General principles, wrong comments It's better to have no comments. So when a piece of code changes, the first thing to do is to modify the comments. Comments should be in English as much as possible. It is best to use complete sentences, with the first letter capitalized. There should be a terminator after the sentence. The terminator should be followed by two spaces to start the next sentence. If it is a phrase, the terminator can be omitted. Comments should be preceded by a space after

# before starting the comment content.

1. Block comments are comments added before a piece of code. Use lines with only ‘#’ between paragraphs. For example:

• # Description : Module config.
  #
  # Input : None
  #
  # Output : None

2. Line comments, add comments after a line of code. You should try to leave two spaces after the statement before starting the comment. When there are continuous line comments, ‘#’ can be aligned for the sake of appearance. When statements are long, line comments should be used as little as possible. for example:

person = {
    "name": "huoty",  # 姓名
    "age": 26,        # 年龄
    "stature": 169,   # 身高
    "weight": 60,     # 体重
}

print person  # 输出信息

• 3、对类或者函数的说明，尽量不要在其定义的前一行或者后一行用块注释的形式来说明，而应该使用文档字符串（docstring）

• 4、使用 TODO 注释来标记待完成的工作，团队协作中，必要的时候应该写上你的名字或者联系方式，比如：

# TODO(sudohuoty@gmail.com): Use a "*" here for string repetition.
# TODO(Huoty) Change this to use relations.

• 5、避免无谓的注释。你见过哪些奇趣的代码注释？

# 你可能会认为你读得懂以下的代码。但是你不会懂的，相信我吧。  

# 要是你尝试玩弄这段代码的话，你将会在无尽的通宵中不断地咒骂自己为什么会认为自己聪明到可以优化这段代码。  
# so，现在请关闭这个文件去玩点别的吧。  

# 程序员1（于2010年6月7日）：在这个坑临时加入一些调料  
# 程序员2（于2011年5月22日）：临你个屁啊  
# 程序员3（于2012年7月23日）：楼上都是狗屎，鉴定完毕  
# 程序员4（于2013年8月2日）：fuck 楼上，三年了，这坑还在！！！  
# 程序员5（于2014年8月21日）：哈哈哈，这坑居然坑了这么多人，幸好我也不用填了，系统终止运行了，you're died

六、文档描述

• 1、尽量为所有的共有模块、函数、类、方法写 docstring。

• 2、前三引号后不应该换行，应该紧接着在后面概括性的说明模块、函数、类、方法的作用，然后再空一行进行详细的说明。后三引号应该单独占一行。比如：

"""Convert an API path to a filesystem path

If given, root will be prepended to the path.
root must be a filesystem path already.
"""

• 2、函数和方法的 docstring 层次顺序大致为概述、详细描述、参数、返回值、异常，一般不要求描述实现细节，除非其中涉及非常复杂的算法。大致的层次结构如下所示：

"""函数或方法的概述

详细的描述信息……
详细的描述信息……

参数说明
--------
    参数1：...
    参数2：...

返回值：
    ...

异常：
    异常1：...
    异常2：...
"""

一个参考示例：

"""Start a kernel for a session and return its kernel_id.                                                                                             

Parameters
----------
kernel_id : uuid
    The uuid to associate the new kernel with. If this
    is not None, this kernel will be persistent whenever it is
    requested.
path : API path
    The API path (unicode, '/' delimited) for the cwd.
    Will be transformed to an OS path relative to root_dir.
kernel_name : str
    The name identifying which kernel spec to launch. This is ignored if
    an existing kernel is returned, but it may be checked in the future.

Return a kernel id
"""

• 3、类的 docstring 的层次顺序大致为概述、详细描述、属性说明。如果类有公开属性值时，应该尽量在 docstring 中进行说明。如下所示：

"""这里是类的概述。

详细的描述信息……
详细的描述信息……

属性(Attributes):
-----------------
    属性1: ...
    属性2: ...
"""

七、命名规范

• 1、模块命名尽量短小，使用全部小写的方式，可以使用下划线。

• 2、包命名尽量短小，使用全部小写的方式，不可以使用下划线。

• 3、类的命名使用驼峰命令的方式，即单词首字符大写，类名应该全部使用名词。

• 4、异常命令应该使用加 Error 后缀的方式，比如：HTTPError。

• 5、全局变量尽量只在模块内有效，并且应该尽量避免使用全局变量。

• 6、函数命名使用全部小写的方式，使用下划线分割单词，并采用动宾结构。

• 7、常量命名使用全部大写的方式，使用下划线分割单词。

• 8、类的属性（方法和变量）命名使用全部小写的方式，使用下划线分割单词。

• 9、变量、类属性等命令尽量不要使用缩写形式，除了计数器和迭代器，尽量不要使用单字符名称。

• 10、类的方法第一个参数必须是 self，而静态方法第一个参数必须是 cls。

• 11、在模块中要表示私有变量或者函数时，可以在变量或者函数前加一个下划线 _foo, _show_msg 来进行访问控制。

• 12、在 Python 中没有诸如 public、private、protected 等修饰符，而在类的定义中往往会有类似这样的需求，那么可以在属性或者方法前加一个下划线表示 protected，加两个下划线来表示 private。加两个下划线的变量或者方法没法直接访问。比如：类 Foo 中声明 __a, 则不能用 Foo.__a 的方式访问，但可以用 Foo._Foo__a 的方式访问。`

八、程序入口

Python 属于脚本语言，代码的运行是通过解释器对代码文件进行逐行解释执行来完成的。它不像其他编程语言那样有统一的入口程序，比如 Java 有 Main 方法，C/C++ 有 main 方法。Python 的代码文件除了可以被直接执行外，还可以作为模块被其他文件导入。所有的顶级代码在模块导入时都会被执行，当希望模块被导入时，应该避免主程序被执行。这样就需要把主程序放到 if __name__ == '__main__' 代码块中，比如：

def main():
      ...

if __name__ == '__main__':
    main()

一个包除了能够被导入外，也可以通过 python -m package 的方式被直接执行，前提是包中需要有 __main__.py，这个文件可以说是包的程序入口，包中有了这个文件就可以用 Python 的 -m 参数来直接运行。

九、编码建议

• 1、尽可能使用 'is' 和 'is not' 取代 '=='，比如 if x is not None 要优于 if x != None，另外用 if x 效率更高。

Note: 等于比较运算符（==） 会调用左操作数的 __eq__ 函数，这个函数可以被其任意定义，而 is 操作只是做 id 比较，并不会被自定义。同时也可以发现 is 函数是要快于等于运算符的，因为不用查找和运行函数。

• 2、用 "is not" 代替 "not ... is"，前者的可读性更好。

• 3、使用基于类的异常，每个模块或包都有自己的异常类，此异常类继承自 Exception。

• 4、异常中尽量不要使用裸露的 except，except 后应该跟具体的 exceptions。

• 5、使用 startswith() 和 endswith() 代替切片进行序列前缀或后缀的检查。

• 6、使用 isinstance() 比较对象的类型，而不是 type()，比如：

# Yes:  
if isinstance(obj, int)

# No:  
if type(obj) is type(1)

• 7、判断序列是否为空时，不用使用 len() 函数，序列为空时其 bool 值为 False，比如：

# Yes:  
if not seq
if seq

# No:  
if len(seq)
if not len(seq)

• 8、字符串后面不要有大量拖尾空格。

• 9、使用 join 合并的字符串，字符串方法 join 可以合并 list、tuple、iterator 中的元素，效率比连接符 + 高。

• 10、使用 while 1 比 while True 更快。

• 11、使用 ** 比 pow 快 10 倍以上。

• 12、使用迭代器和生成器代替列表等数据结构效率更高，使用列表（字典）解析式和生成器表达式比用循环效率更高。

• 13、避免在循环中用 + 或 += 来连续拼接字符串。因为字符串是不变型，这会毫无必要地建立很多临时对象，从而成为二次方级别的运算量而不是线性运算时间。

• 14、多去了解标准库，标准库中用很多好用的功能，能够更优雅的解决问题，如 pkgutil.get_data()、operator.methodcaller() 等等。

The above is the detailed content of Detailed introduction to Python coding format (with examples). For more information, please follow other related articles on the PHP Chinese website!