Python

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

Posted by FanHao on 2019-04-12

前言

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

参考

若需要阅读Google官方python代码风格指导文档，请点击这里。

对于以下文档中没有提到规范，你可以使用python模块pylint检查你的python代码是否符合规范。

1
pip3 install pylint

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

代码规范

编码

  1. 无特殊情况，代码文件一律使用utf-8编码

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

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

  1. import语句需分行书写。

    1
    2
    3
    4
    5
    6
    7
    # 正确的写法
    import sys
    import time
    from subprocess import Popen, PIPE

    # 不推荐的写法
    import sys, time

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

    1
    2
    3
    4
    5
    # 正确的写法
    from foo.bar import Bar

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

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

    1
    2
    3
    4
    5
    # -*- coding: utf-8 -*-
    """
    This is a Test program
    """
    import sys

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

    1
    2
    3
    4
    5
    6
    # 以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导入。

    1
    2
    3
    4
    5
    import xlrd

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

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

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

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

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

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

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

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

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

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

    1
    2
    3
    4
    5
    # 正确的写法
    dict['key'] = list[index]
     
    # 不推荐的写法
    dict ['key'] = list [index]

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

    1
    2
    3
    4
    5
    6
    7
    8
    # 正确的写法
    a = 1
    b = 33
    name = 'test'
    # 不正确的写法
    a    = 1
    b    = 33
    name = 'test'
换行

python支持括号内的换行。

docstring规范

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

  1. 所有的公共模块、函数、类、方法，都必须写 docstring 。私有方法不一定需要，但应该在 def 后提供一个块注释来说明。

  2. docstring 的结束”””应该独占一行，除非此 docstring 只有一行。

    1
    2
    3
    4
    5
    6
    7
    # docstring写在如下位置
    class Test():
        """class Test
        """
        def func():
            """func"""
            pass
文件处理规范

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

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

命名规范

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

    1
    main.py

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

    1
    flask

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

    1
    class WinMain:

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

    1
    PERSON_NAME = "Fan"

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

    1
    2
    name = ''
    your_name = 'Alan'

  6. 实例变量，以一个下划线_开头，如有多个单词，用下划线隔开。

    用单下划线(_)开头表示模块变量或函数是protected的(使用import * from时不会包含).

    1
    self._your_name = ''

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

    1
    __name__ = ''

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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    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。全部小写，单词之间用下划线分隔。

    1
    def test_method():

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

    1
    2
    is_true = True
    has_name = True

注释规范

  1. 行注释

    “#”号后空一格。

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

  2. 块注释

    如下所示，也是用”#”。

    1
    2
    3
    4
    5
    # 块注释
    # 块注释
    # 
    # 块注释
    # 块注释

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

    1
    2
    3
    4
    5
    6
    7
    8
    app = create_app(name, options)

    # =============================
    # 请不要修改此部分的代码
    # =============================

    if __name__ == "__main__":
        app.run

  3. 文档注释（docstring）

    作为文档的Docstring一般出现在模块头部、函数和类的头部，这样在python中可以通过对象的__doc__获取文档信息。编辑器和IDE也可以根据Docstring给出自动提示。

    文档注释以 “”” 开头和结尾, 首行不换行, 如有多行, 末行必需换行。以下为文件头部的docstring。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    # -*- 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。具体描述其具体内容以及实现的功能，解释具体参数和返回值等。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    class WinMain(QtGui.QMainWindow):
        """程序主窗口类，主要实现生成ui界面。
        另外包括
        """
        def init_config(self):
            """初始化工具程序界面的配置参数，
           	没有返回值
            """
            pass
FEATURED TAGS
Python
FRIENDS