1. 程式人生 > >Python代碼規範

Python代碼規範

vat dict 復制 獲取 function sso hello private tty

前言

Python 學習之旅,先來看看 Python 的代碼規範,讓自己先有個意識,而且在往後的學習中慢慢養成習慣

目錄

Python代碼規範

一、簡明概述

  • 1、編碼

    如無特殊情況, 文件一律使用 UTF-8 編碼
    如無特殊情況, 文件頭部必須加入#--coding:utf-8--標識

  • 2、代碼格式

    2.1、縮進
    統一使用 4 個空格進行縮進
    2.2、行寬
    每行代碼盡量不超過 80 個字符(在特殊情況下可以略微超過 80 ,但最長不得超過 120)
    理由:
    這在查看 side-by-side 的 diff 時很有幫助
    方便在控制臺下查看代碼


    太長可能是設計有缺陷

  • 2.3、引號

    簡單說,自然語言使用雙引號,機器標示使用單引號,因此 代碼裏 多數應該使用 單引號
    自然語言 使用雙引號 “…”
    例如錯誤信息;很多情況還是 unicode,使用u”你好世界”
    機器標識 使用單引號 ‘…’
    例如 dict 裏的 key
    正則表達式 使用原生的雙引號 r”…”
    文檔字符串 (docstring) 使用三個雙引號 “”“……”“”

  • 2.4、空行
    模塊級函數和類定義之間空兩行;
    類成員函數之間空一行;
    class A:

        def __init__(self):
            pass

        def hello(self):
            pass

    def main():
        pass   
 ```
可以使用多個空行分隔多組相關的函數
函數中可以使用空行分隔出邏輯相關的代碼
- 2.5、編碼
>文件使用 UTF-8 編碼
文件頭部加入#-*-conding:utf-8-*-標識
- 3、import 語句
``
`正確的寫法
import os
import sys
不推薦的寫法
import sys,os
正確的寫法
from subprocess import Popen, PIPE
import語句應該使用 absolute import
 正確的寫法
from foo.bar import Bar
不推薦的寫法
from ..bar import Bar
import語句應該放在文件頭部,置於模塊說明及docstring之後,於全局變量之前;
import語句應該按照順序排列,每組之間用一個空行分隔
import os
import sys

import msgpack
import zmq

import foo
導入其他模塊的類定義時,可以使用相對導入
from myclass import MyClass
如果發生命名沖突,則可使用命名空間
import bar
import foo.bar

bar.Bar()
foo.bar.Bar()


.4、空格

在二元運算符兩邊各空一格[=,-,+=,==,>,in,is not, and]:

正確的寫法
i = i + 1
submitted += 1
x = x * 2 - 1
hypot2 = x * x + y * y
c = (a + b) * (a - b)

不推薦的寫法
i=i+1
submitted +=1
x = x*2 - 1
hypot2 = x*x + y*y
c = (a+b) * (a-b)
函數的參數列表中,,之後要有空格
正確的寫法
def complex(real, imag):
    pass

 不推薦的寫法
def complex(real,imag):
    pass
函數的參數列表中,默認值等號兩邊不要添加空格
 正確的寫法
def complex(real, imag=0.0):
    pass

 不推薦的寫法
def complex(real, imag = 0.0):
    pass
左括號之後,右括號之前不要加多余的空格
 正確的寫法
spam(ham[1], {eggs: 2})

不推薦的寫法
spam( ham[1], { eggs : 2 } )
字典對象的左括號之前不要多余的空格
正確的寫法
dict[‘key‘] = list[index]

不推薦的寫法
dict [‘key‘] = list [index]
不要為對齊賦值語句而使用的額外空格
正確的寫法
x = 1
y = 2
long_variable = 3

 不推薦的寫法
x             = 1
y             = 2
long_variable = 3
  • 5、換行
Python 支持括號內的換行。這時有兩種情況。
1) 第二行縮進到括號的起始處
foo = long_function_name(var_one, var_two,
                         var_three, var_four)
2) 第二行縮進 4 個空格,適用於起始括號就換行的情形
def long_function_name(
        var_one, var_two, var_three,
        var_four):
    print(var_one)
使用反斜杠\換行,二元運算符+ .等應出現在行末;長字符串也可以用此法換行
session.query(MyTable).        filter_by(id=1).        one()

print ‘Hello, ‘      ‘%s %s!‘ %      (‘Harry‘, ‘Potter‘)
禁止復合語句,即一行中包含多個語句:
正確的寫法
do_first()
do_second()
do_third()

不推薦的寫法
do_first();do_second();do_third();
if/for/while一定要換行:
正確的寫法
if foo == ‘blah‘:
    do_blah_thing()

不推薦的寫法
if foo == ‘blah‘: do_blash_thing()
  • 6、docstring
docstring 的規範中最其本的兩點:
所有的公共模塊、函數、類、方法,都應該寫 docstring 。私有方法不一定需要,但應該在 def 後提供一個塊註釋來說明。
docstring 的結束"""應該獨占一行,除非此 docstring 只有一行。
"""Return a foobar
Optional plotz says to frobnicate the bizbaz first.
"""

"""Oneline docstring"""

二、註釋

  • 1、註釋
1.1、塊註釋
“#”號後空一格,段落件用空行分開(同樣需要“#”號)
# 塊註釋
# 塊註釋
#
# 塊註釋
# 塊註釋
1.2、行註釋
至少使用兩個空格和語句分開,註意不要使用無意義的註釋
# 正確的寫法
x = x + 1  # 邊框加粗一個像素

# 不推薦的寫法(無意義的註釋)
x = x + 1 # x加1
1.3、建議
在代碼的關鍵部分(或比較復雜的地方), 能寫註釋的要盡量寫註釋
比較重要的註釋段, 使用多個等號隔開, 可以更加醒目, 突出重要性
app = create_app(name, options)

# =====================================
# 請勿在此處添加 get post等app路由行為 !!!
# =====================================

if __name__ == ‘__main__‘:
    app.run()
  • 2、文檔註釋(Docstring)
作為文檔的Docstring一般出現在模塊頭部、函數和類的頭部,這樣在python中可以通過對象的__doc__對象獲取文檔.
編輯器和IDE也可以根據Docstring給出自動提示.
文檔註釋以 """ 開頭和結尾, 首行不換行, 如有多行, 末行必需換行, 以下是Google的docstring風格示例
# -*- coding: utf-8 -*-
"""Example docstrings.

This module demonstrates documentation as specified by the `Google Python
Style Guide`_. Docstrings may extend over multiple lines. Sections are created
with a section header and a colon followed by a block of indented text.

Example:
    Examples can be given using either the ``Example`` or ``Examples``
    sections. Sections support any reStructuredText formatting, including
    literal blocks::

        $ python example_google.py

Section breaks are created by resuming unindented text. Section breaks
are also implicitly created anytime a new section starts.
"""
不要在文檔註釋復制函數定義原型, 而是具體描述其具體內容, 解釋具體參數和返回值等
#  不推薦的寫法(不要寫函數原型等廢話)
def function(a, b):
    """function(a, b) -> list"""
    ... ...

#  正確的寫法
def function(a, b):
    """計算並返回a到b範圍內數據的平均值"""
    ... ...
對函數參數、返回值等的說明采用numpy標準, 如下所示
def func(arg1, arg2):
    """在這裏寫函數的一句話總結(如: 計算平均值).

    這裏是具體描述.

    參數
    ----------
    arg1 : int
        arg1的具體描述
    arg2 : int
        arg2的具體描述

    返回值
    -------
    int
        返回值的具體描述

    參看
    --------
    otherfunc : 其它關聯函數等...

    示例
    --------
    示例使用doctest格式, 在`>>>`後的代碼可以被文檔測試工具作為測試用例自動運行

    >>> a=[1,2,3]
    >>> print [x + 3 for x in a]
    [4, 5, 6]
    """
文檔註釋不限於中英文, 但不要中英文混用
文檔註釋不是越長越好, 通常一兩句話能把情況說清楚即可
模塊、公有類、公有方法, 能寫文檔註釋的, 應該盡量寫文檔註釋

三、命名規範

  • 1、模塊
模塊盡量使用小寫命名,首字母保持小寫,盡量不要用下劃線(除非多個單詞,且數量不多的情況)
# 正確的模塊名
import decoder
import html_parser

# 不推薦的模塊名
import Decoder
  • 2、類名
類名使用駝峰(CamelCase)命名風格,首字母大寫,私有類可用一個下劃線開頭
class Farm():
    pass

class AnimalFarm(Farm):
    pass

class _PrivateFarm(Farm):
    pass
將相關的類和頂級函數放在同一個模塊裏. 不像Java, 沒必要限制一個類一個模塊.
  • 3、函數
函數名一律小寫,如有多個單詞,用下劃線隔開
def run():
    pass

def run_with_env():
    pass
私有函數在函數前加一個下劃線_
class Person():

    def _private_func():
        pass
  • 4、變量名
變量名盡量小寫, 如有多個單詞,用下劃線隔開
if __name__ == ‘__main__‘:
    count = 0
    school_name = ‘‘
常量采用全大寫,如有多個單詞,使用下劃線隔開
MAX_CLIENT = 100
MAX_CONNECTION = 1000
CONNECTION_TIMEOUT = 600

5、常量

常量使用以下劃線分隔的大寫命名
MAX_OVERFLOW = 100

Class FooBar:

    def foo_bar(self, print_):
        print(print_)

Python代碼規範