【Python】編程代碼書寫規範！

程序不僅僅是給機器看的，自己在回顧的時候也會查看。如果在團隊開發中，規範的編程習慣以及優良的註釋會大大地提高團隊的開發效率。現在來看看Python中有哪些編程規範。

1 編碼

無特殊情況，建議Python腳本程序一律使用 UTF-8 編碼，並且在文件頭部必須加入#-*-coding:utf-8-*-標識，聲明文件編碼方式，程序文件編碼要和聲明編碼保持一致。

2 代碼格式

縮進： 統一使用 4 個空格進行縮進。（默認一個tab鍵就是4個空格，有時程序格式問題可能出現在這裏，tab鍵不一定就是4個空格）

行寬： 每行代碼儘量不超過 80 個字符(在特殊情況下可以略微超過 80 ，但最長不得超過 120)。如果代碼過長，說明代碼設計方面可能不合理。除此之外也方便在控制檯查看代碼(linux)以及通過對side-by-side的diff時有幫助。

引號：自然語言，也就是說一般使用雙引號；機器標示使用單引號，例如字典中的key，正則表達式使用原生的雙引號 r"..."；文檔字符串 (docstring) 使用三個雙引號 """ ......"""。當然實際中需要靈活運用，畢竟三種引號使用是有區別的。

空行：

模塊級函數和類定義之間空兩行；
類成員函數之間空一行；

如下代碼：

class A:
# one line
    def __init__(self):
        pass
# one line
    def hello(self):
        pass
# one line
# one line
def main():
    pass

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

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語句應該按照順序排列，每組之間用一個空行分隔(也就是說同一類型的在一塊)
導入其他模塊的類定義時，可以使用相對導入

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 支持括號內的換行。這時有兩種情況，如下：

第二行縮進到括號的起始處

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

第二行縮進 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 docstrings

docstrings，文檔註釋，用於解釋文檔程序，幫助你的程序文檔更加簡單易懂。docstring 的規範中最其本的兩點：

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

"""Return a foobar
Optional plotz says to frobnicate the bizbaz first.
"""

"""Oneline 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]
    """

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

7 註釋

塊註釋 ：“#”號後空一格，段落件用空行分開（同樣需要“#”號）

# 塊註釋
#
# 塊註釋

行註釋： 至少使用兩個空格和語句分開，不要使用無意義的註釋

# 正確的寫法
x = x + 1  # 邊框加粗一個像素

# 不推薦的寫法(無意義的註釋)
x = x + 1 # x加1

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

app = create_app(name, options)


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


if __name__ == '__main__':
    app.run()

8 命名規範

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

# 正確的模塊名
import decoder
import html_parser

# 不推薦的模塊名
import Decoder

類名：類名使用駝峯(CamelCase)命名風格，首字母大寫，私有類可用一個下劃線開頭;將相關的類和頂級函數放在同一個模塊裏. 不像Java, 沒必要限制一個類一個模塊。

class Farm():
    pass

class AnimalFarm(Farm):
    pass

class _PrivateFarm(Farm):
    pass

函數：

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

def run():
    pass

def run_with_env():
    pass

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

class Person():

    def _private_func():
        pass

變量名

變量名儘量小寫, 如有多個單詞，用下劃線隔開

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

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

MAX_CLIENT = 100
MAX_CONNECTION = 1000
CONNECTION_TIMEOUT = 600

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

MAX_OVERFLOW = 100

Class FooBar:

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

總結

現在一般的編輯器和IDE都會有格式提醒，python的代碼錯誤檢查通常用pep8、pylint和flake8規範，這些規範對代碼格式要求也不同，掌握以上的規範也大致差不多了，也可以安裝pep8、pylint或flake8相關包，編程時會有相對的提醒，輔助我們的編程！

【Python】編程代碼書寫規範！

1 編碼

2 代碼格式

3 import語句

4 空格使用

5 換行

6 docstrings

7 註釋

8 命名規範

總結

【數學理論】最優化問題:拉格朗日乘子法、KKT條件以及對偶問題

【開發工具】Linux-CentOS安裝Anaconda

【機器學習】吳恩達機器學習視頻作業-（手撕）神經網絡

【機器學習】EM算法詳解

【Go】指針

Mac下配置sublime實現LaTeX

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結