前言

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 語句應該分行書寫

# 正確的寫法
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 程式碼規範

前言

目錄