python 代码规范和命名规范说明

Question

之前一直使用 sublime 编辑器编写 python 代码，后面使用 vs code 编辑器打开项目文件时，发现有很多规范上的问题。特地总结一下编写 python 代码规范，编写代码时还是需要严格遵守代码规范。

参考

若需要阅读 Google 官方 python 代码风格指导文档，请点击 这里 。 对于以下文档中没有提到规范，你可以使用 python 模块 pylint 检查你的 python 代码是否符合规范。

pip3 install pylint

在这里推荐使用 VS code 编辑器，安装 pylint 后。打开你的项目文件，查看是否存在代码规范问题。

代码规范

编码

1. 无特殊情况，代码文件一律使用 utf-8 编码
2. 无特殊情况，代码文件头部必须加入 # -- coding: utf-8 --

   # -*- coding: utf-8 -*-

代码格式

1. 缩进：一律使用 4 个空格缩进。禁止空格和 tab 键混合使用，否则会报错。
2. 行宽：每行代码尽量不超过 80 个字符，最长不得超过 120 个字符。
3. 引号：自然语言使用双引号，也可以使用 unicode，如 u”错误”。机器标识语言使用单引号 ‘ ‘，如 dict 中 key 值。正则表达式使用原生双引号，如 r“…”。文档字符串使用三个双引号，如 ”””….”””。

import 语句

1. import 语句需分行书写。

   # 正确的写法
   import sys
   import time
   from subprocess import Popen, PIPE
   
   # 不推荐的写法
   import sys, time

2. import 语句需使用绝对导入（absolute import）。

   # 正确的写法
   from foo.bar import Bar
   
   # 不推荐的写法
   from ..bar import Bar

3. import 语句应该放在文件头部，置于模块说明及 docstring 之后，于全局变量之前。

   # -*- coding: utf-8 -*-
   """
   This is a Test program
   """
   import sys

4. import 语句应该按照顺序排列，每组之间用一个空行分隔。

   # 以 flask 库的 wrappers.py 文件为例，以下为该文件导入的包
   from werkzeug.exceptions import BadRequest
   from werkzeug.wrappers import Request as RequestBase, Response as ResponseBase
   
   from flask import json
   from flask.globals import current_app

5. 如果你的代码里没有使用到该模块，就不需要用 import 导入。

   import xlrd
   
   # 代码不需要 xlrd 库，不需要写以上 import xlrd 代码
   def test():
       pass

空格

1. 在二元运算符两边各空一格 [=,-,+=,==,>,in,is not, and] :

   # 正确的写法
   i = i + 1
   submitted += 1
   x = x * 2 - 1
   hypot2 = x * x + y * y
   c = (a + b) * (a - b)

2. 函数的参数列表中， , 之后要有空格

   # 正确的写法
   def plus_func(a, b):
       pass

3. 函数的参数列表中，默认值等号两边不要添加空格

   # 正确写法
   def plus_func(a=1, b):
       pass

4. 左括号之后，右括号之前不要加多余的空格

   # 正确的写法
   spam(ham[1], {eggs: 2})
    
   # 不推荐的写法
   spam( ham[1], { eggs : 2 } )

5. 字典对象的左括号之前不要多余的空格

   # 正确的写法
   dict['key'] = list[index]
    
   # 不推荐的写法
   dict ['key'] = list [index]

6. 不要为对齐赋值语句而使用的额外空格

   # 正确的写法
   a = 1
   b = 33
   name = 'test'
   # 不正确的写法
   a    = 1
   b    = 33
   name = 'test'

换行

python 支持括号内的换行。

docstring 规范

docstring 中文可称为文档字符串。python 独有的一种注释方式。通过这样注释的字符串能够被对象的__doc__方法自动获取。

1. 所有的公共模块、函数、类、方法，都必须写 docstring 。私有方法不一定需要，但应该在 def 后提供一个块注释来说明。
2. docstring 的结束”””应该独占一行，除非此 docstring 只有一行。

   # docstring 写在如下位置
   class Test():
       """class Test
       """
       def func():
           """func"""
           pass

文件处理规范

推荐使用 “with”语句处理文件

# 推荐用法
with open("hello.txt") as hello_file:
    for line in hello_file:
        print line

命名规范

1. 模块名，module。全部小写，单词之间用下划线分隔。

   main.py

2. 包名，package。全部小写，单词之间用下划线分隔。

   flask

3. 类名，class。首字母大写，驼峰式命名。

   class WinMain:

4. 全局变量（常量），global variables。全部大写，单词之间用下划线分隔。

   PERSON_NAME = "Fan"

5. 变量，variables。这里默认为 public 类型的变量。变量名尽量小写, 如有多个单词，用下划线隔开。

   name = ''
   your_name = 'Alan'

6. 实例变量，以一个下划线_开头，如有多个单词，用下划线隔开。 用单下划线(_) 开头表示模块变量或函数是 protected 的（使用 import * from 时不会包含).

   self._your_name = ''

7. 内置变量（专有变量）。这类变量一般不用我们定义。以两个下划线__开头，两个下划线结尾

   __name__ = ''

8. 用双下划线(__) 开头的实例变量或方法表示为私有变量或私有方法

   class Test():
       """Test"""
       # protected 型变量
       _name = 'protected variable'
       # 私有 private 变量
       __info = 'private variable'
       def _func1():
           """protected"""
           print("这是一个 protected 方法")
       def __func2():
           """private 私有"""
           print("这是一个 private 方法")
       def print_func():
           """public 公共"""
           print('这个一个 public 方法')

9. 函数方法，function/method。全部小写，单词之间用下划线分隔。

   def test_method():

10. 标志位，以 has 或 is，下划线分隔单词命名

    is_true = True
    has_name = True

注释规范

1. 行注释 “#”号后空一格。

   # 推荐的写法
   def test():
       print('行注释')   # 打印

2. 块注释 如下所示，也是用”#”。

   # 块注释
   # 块注释
   # 
   # 块注释
   # 块注释

   在关键代码部分可以使用更加项目的注释

   app = create_app(name, options)
   
   # =============================
   # 请不要修改此部分的代码
   # =============================
   
   if __name__ == "__main__":
       app.run

3. 文档注释（docstring） 作为文档的 Docstring 一般出现在模块头部、函数和类的头部，这样在 python 中可以通过对象的__doc__获取文档信息。编辑器和 IDE 也可以根据 Docstring 给出自动提示。 文档注释以 “”” 开头和结尾, 首行不换行, 如有多行, 末行必需换行。以下为文件头部的 docstring。

   # -*- coding: utf-8 -*-
   """Example docstring
   	flask.app
       ~~~~~~~~~
   
       This module implements the central WSGI application object.
   
       :copyright: © 2010 by the Pallets team.
       :license: BSD, see LICENSE for more details.
   """

   类和函数的头部定义的 docstring。具体描述其具体内容以及实现的功能，解释具体参数和返回值等。

   class WinMain(QtGui.QMainWindow):
       """程序主窗口类，主要实现生成 ui 界面。
       另外包括
       """
       def init_config(self):
           """初始化工具程序界面的配置参数，
          	没有返回值
           """
           pass