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:nn def __init__(self):n passnn def hello(self):n passnnndef main():n passn

  • 可以使用多個空行分隔多組相關的函數
  • 函數中可以使用空行分隔出邏輯相關的代碼

2.5、編碼

  • 文件使用 UTF-8 編碼
  • 文件頭部加入#-*-conding:utf-8-*-標識

3、import 語句

  • import 語句應該分行書寫

# 正確的寫法nimport osnimport sysnn# 不推薦的寫法nimport sys,osnn# 正確的寫法nfrom subprocess import Popen, PIPEn

  • import語句應該使用 absolute import

# 正確的寫法nfrom foo.bar import Barnn# 不推薦的寫法nfrom ..bar import Barn

  • import語句應該放在文件頭部,置於模塊說明及docstring之後,於全局變數之前;
  • import語句應該按照順序排列,每組之間用一個空行分隔

import osnimport sysnnimport msgpacknimport zmqnnimport foon

  • 導入其他模塊的類定義時,可以使用相對導入

from myclass import MyClassn

  • 如果發生命名衝突,則可使用命名空間

import barnimport foo.barnnbar.Bar()nfoo.bar.Bar()n

4、空格

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

# 正確的寫法ni = i + 1nsubmitted += 1nx = x * 2 - 1nhypot2 = x * x + y * ync = (a + b) * (a - b)nn# 不推薦的寫法ni=i+1nsubmitted +=1nx = x*2 - 1nhypot2 = x*x + y*ync = (a+b) * (a-b)n

  • 函數的參數列表中,,之後要有空格

# 正確的寫法ndef complex(real, imag):n passnn# 不推薦的寫法ndef complex(real,imag):n passn

  • 函數的參數列表中,默認值等號兩邊不要添加空格

# 正確的寫法ndef complex(real, imag=0.0):n passnn# 不推薦的寫法ndef complex(real, imag = 0.0):n passn

  • 左括弧之後,右括弧之前不要加多餘的空格

# 正確的寫法nspam(ham[1], {eggs: 2})nn# 不推薦的寫法nspam( ham[1], { eggs : 2 } )n

  • 字典對象的左括弧之前不要多餘的空格

# 正確的寫法ndict[key] = list[index]nn# 不推薦的寫法ndict [key] = list [index]n

  • 不要為對齊賦值語句而使用的額外空格

# 正確的寫法nx = 1ny = 2nlong_variable = 3nn# 不推薦的寫法nx = 1ny = 2nlong_variable = 3n

5、換行

Python 支持括弧內的換行。這時有兩種情況。

1) 第二行縮進到括弧的起始處

foo = long_function_name(var_one, var_two,n var_three, var_four)n

2) 第二行縮進 4 個空格,適用於起始括弧就換行的情形

def long_function_name(n var_one, var_two, var_three,n var_four):n print(var_one)n

使用反斜杠`換行,二元運算符+.`等應出現在行末;長字元串也可以用此法換行

session.query(MyTable).n filter_by(id=1).n one()nnprint Hello, n %s %s! %n (Harry, Potter)n

禁止複合語句,即一行中包含多個語句:

# 正確的寫法ndo_first()ndo_second()ndo_third()nn# 不推薦的寫法ndo_first();do_second();do_third();n

if/for/while一定要換行:

# 正確的寫法nif foo == blah:n do_blah_thing()nn# 不推薦的寫法nif foo == blah: do_blash_thing()n

6、docstring

docstring 的規範中最其本的兩點:

  1. 所有的公共模塊、函數、類、方法,都應該寫 docstring 。私有方法不一定需要,但應該在 def 後提供一個塊注釋來說明。
  2. docstring 的結束"""應該獨佔一行,除非此 docstring 只有一行。

"""Return a foobarnOptional plotz says to frobnicate the bizbaz first.n"""nn"""Oneline docstring"""n

二、注釋

1、注釋

1.1、塊注釋

「#」號後空一格,段落件用空行分開(同樣需要「#」號)

# 塊注釋n# 塊注釋n#n# 塊注釋n# 塊注釋n

1.2、行注釋

至少使用兩個空格和語句分開,注意不要使用無意義的注釋

# 正確的寫法nx = x + 1 # 邊框加粗一個像素nn# 不推薦的寫法(無意義的注釋)nx = x + 1 # x加1n

1.3、建議

  • 在代碼的關鍵部分(或比較複雜的地方), 能寫注釋的要盡量寫注釋
  • 比較重要的注釋段, 使用多個等號隔開, 可以更加醒目, 突出重要性

app = create_app(name, options)nnn# =====================================n# 請勿在此處添加 get post等app路由行為 !!!n# =====================================nnnif __name__ == __main__:n app.run()n

2、文檔注釋(Docstring)

作為文檔的Docstring一般出現在模塊頭部、函數和類的頭部,這樣在python中可以通過對象的__doc__對象獲取文檔.

編輯器和IDE也可以根據Docstring給出自動提示.

  • 文檔注釋以 """ 開頭和結尾, 首行不換行, 如有多行, 末行必需換行, 以下是Google的docstring風格示例

# -*- coding: utf-8 -*-n"""Example docstrings.nnThis module demonstrates documentation as specified by the `Google PythonnStyle Guide`_. Docstrings may extend over multiple lines. Sections are creatednwith a section header and a colon followed by a block of indented text.nnExample:n Examples can be given using either the ``Example`` or ``Examples``n sections. Sections support any reStructuredText formatting, includingn literal blocks::nn $ python example_google.pynnSection breaks are created by resuming unindented text. Section breaksnare also implicitly created anytime a new section starts.n"""n

  • 不要在文檔注釋複製函數定義原型, 而是具體描述其具體內容, 解釋具體參數和返回值等

# 不推薦的寫法(不要寫函數原型等廢話)ndef function(a, b):n """function(a, b) -> list"""n ... ...nnn# 正確的寫法ndef function(a, b):n """計算並返回a到b範圍內數據的平均值"""n ... ...n

  • 對函數參數、返回值等的說明採用numpy標準, 如下所示

def func(arg1, arg2):n """在這裡寫函數的一句話總結(如: 計算平均值).nn 這裡是具體描述.nn 參數n ----------n arg1 : intn arg1的具體描述n arg2 : intn arg2的具體描述nn 返回值n -------n intn 返回值的具體描述nn 參看n --------n otherfunc : 其它關聯函數等...nn 示例n --------n 示例使用doctest格式, 在`>>>`後的代碼可以被文檔測試工具作為測試用例自動運行nn >>> a=[1,2,3]n >>> print [x + 3 for x in a]n [4, 5, 6]n """n

  • 文檔注釋不限於中英文, 但不要中英文混用
  • 文檔注釋不是越長越好, 通常一兩句話能把情況說清楚即可
  • 模塊、公有類、公有方法, 能寫文檔注釋的, 應該盡量寫文檔注釋

三、命名規範

1、模塊

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

# 正確的模塊名nimport decodernimport html_parsernn# 不推薦的模塊名nimport Decodern

2、類名

  • 類名使用駝峰(CamelCase)命名風格,首字母大寫,私有類可用一個下劃線開頭

class Farm():n passnnclass AnimalFarm(Farm):n passnnclass _PrivateFarm(Farm):n passn

  • 將相關的類和頂級函數放在同一個模塊里. 不像Java, 沒必要限制一個類一個模塊.

3、函數

  • 函數名一律小寫,如有多個單詞,用下劃線隔開

def run():n passnndef run_with_env():n passn

  • 私有函數在函數前加一個下劃線_

class Person():nn def _private_func():n passn

4、變數名

  • 變數名盡量小寫, 如有多個單詞,用下劃線隔開

if __name__ == __main__:n count = 0n school_name = n

  • 常量採用全大寫,如有多個單詞,使用下劃線隔開

MAX_CLIENT = 100nMAX_CONNECTION = 1000nCONNECTION_TIMEOUT = 600n

5、常量

  • 常量使用以下劃線分隔的大寫命名

MAX_OVERFLOW = 100nnClass FooBar:nn def foo_bar(self, print_):n print(print_)n

推薦閱讀:

python和C#結合的效果如何?是否能讓C#寫的程序調用python的庫?
如何高效自學編程()?
如何用三個月學會python?
在python中,怎樣計算list的累積和?不能用loop或者library的function。
新手小白請教maya python ?

TAG:Python | Python入门 |