Python基礎篇四 編碼規範

在用pycharm編碼的過程中，發現會有很多關於編程規範的小提示，雖然之前看了一些python的編碼規範，但寫起來還是覺得差了很多。

既然自詡了“文藝犯二”，又怎能允許寫出來的代碼不漂亮呢？
於是花了很多時間蒐羅python的編碼規範，原來python官網就有啊！深深覺得自己孤陋寡聞了。

PEP: Python Enhancement Proposals（python優化建議）PEP的內容非常的豐富，其中關於編碼規範可以參考以下兩個index
PEP8: Style Guide for Python Code
https://legacy.python.org/dev/peps/pep-0008/

PEP257：Docstring Conventions
https://legacy.python.org/dev/peps/pep-0257/

================================
原則：編碼規範最基本的原則是一致性！
一個項目中的一致性非常重要!
不要爲了遵守PEP而破壞向後兼容性。
===============================

代碼佈局

1. 每個級別的縮進使用4個空格。
2. 每行最大長度79，文檔註釋一類的不超過72個字符。換行可以使用反斜槓，也可用()括起一條換行的語句。 換行點要在操作符之前，這樣可以保證操作符對齊。
3. 關於空行：類和top-level函數定義之間空兩行；類中方法定義之間空一行；函數內無關代碼段之間空一行；其它地方儘量不要再空行。
4. 不要將多條語句寫在同一行，雖然python支持用“;”來分隔一行裏的多條語句，但仍然不推薦這樣寫。
5. python中的“;”作用就是爲了分隔一行中的多條語句，雖然行尾加與不加“;”都可以正常編譯，但推薦遵循python的特點，不加“;”
6. if/for/while語句中，即使執行語句只有一句，也推薦另起一行。

---

文檔編排

1. 模塊內容順序：模塊說明& docstring -->import （標準庫-> 第三方庫->自定義庫，之間空一行）–> global&constants -->其它定義。
2. 不要在一句import中引入多個庫。

---

空格

1. 各種右括號之前不加空格
2. 逗號、冒號、分號之前不加空格
3. 函數左括號之前不加空格
4. 序列左括號之前不加空格
5. 操作符左右各加一個空格，不要爲了對齊增加空格
6. 函數默認參數使用的賦值符左右省略空格

---

註釋

1. 錯誤的註釋不如沒有註釋，所以當修改代碼時，第一件事就是修改註釋！（這條適用於所有語言）
2. 要使用英文，最好是完整的句子，大寫開頭，句號結尾。
3. 塊註釋：在“#”後加一空格，跟註釋。
4. 行註釋不推薦使用
5. 避免無用的註釋

---

文檔描述

1. 爲所有的共有模塊、函數、類、方法寫docstrings；非共有的沒有必要，但是可以寫註釋（在def的下一行）

---

命名規範

1. 命名儘量從使用的角度而非實現的角度。
2. 儘量避免使用小寫字母‘l’，大寫字母‘O’等容易混淆的字母。
3. 模塊命名儘量短小，使用全部小寫的方式，可以使用下劃線。
4. 包命名儘量短小，使用全部小寫的方式，不可以使用下劃線。
5. 類的命名使用CapWords的方式，模塊內部使用的類採用_CapWords的方式。
6. 異常命名使用CapWords+Error後綴的方式。
7. 全局變量儘量只在模塊內有效，類似C語言中的static。實現方法有兩種，一是__all__機制;二是前綴一個下劃線。放在模塊的docstring和from __future__之後，import之前。
8. 函數命名使用全部小寫的方式，可以使用下劃線分隔語意。
9. 常量命名使用全部大寫的方式，可以使用下劃線。
10. 類的屬性（方法和變量）命名使用全部小寫的方式，可以使用下劃線。
11. 類的屬性有3種作用域public、non-public和subclass ，可以理解成C++中的public、private、protected，non-public屬性前，前綴加一個下劃線。
12. 類的屬性若與關鍵字名字衝突，後綴加下劃線，儘量不要使用縮略等其他方式。
13. 爲避免與子類屬性命名衝突，在類的一些屬性前，前綴兩條下劃線。比如：類Foo中聲明__a,訪問時，只能通過Foo._Foo__a，避免歧義。如果子類也叫Foo，那就無能爲力了。
14. 類的方法第一個參數必須是self，而靜態方法第一個參數必須是cls。

---

關於import

import bench                 # 此爲 implicit relative import
from . import bench          # 此爲 explicit relative import
from furniture import bench  # 此爲 absolute import

第一種隱式相對導入，python3已經廢棄，只能用於導入path中的模塊
第二種顯示相對導入
第三種絕對導入，是推薦的import方式。

---

跨行語句示例

<示例1>
# 與打開的括號對齊
foo = long_function_name(var_one, var_two,
                        var_three, var_four)
# 懸掛式，首行無參數
foo = long_function_name(
   var_one, var_two,
   var_three, var_four)

<示例2>
# 加一行註釋，增加可讀性
# supporting syntax highlighting.
if (this_is_one_thing and
    that_is_another_thing):
    # Since both conditions are true, we can frobnicate.
    do_something()

# 在續行上增加一級縮進
if (this_is_one_thing
        and that_is_another_thing):
    do_something()

<示例3>
# 打開的右括號在最後一行對齊第一個非空格字符
my_list = [
    1, 2, 3,
    4, 5, 6,
    ]
result = some_function_that_takes_arguments(
    'a', 'b', 'c',
    'd', 'e', 'f',
    )

---

推薦&不推薦

== YES ==>
def foo(x):
   if x >= 0:
       return math.sqrt(x)
   else:
       return None

def bar(x):
   if x < 0:
       return None
   return math.sqrt(x)

<== NO ==
def foo(x):
   if x >= 0:
       return math.sqrt(x)

def bar(x):
   if x < 0:
       return
   return math.sqrt(x)

== YES ==>
if foo.startswith('bar'):

<== NO ==
if foo[:3] == 'bar':

== YES ==>
if isinstance(obj, int):

<== NO ==
if type(obj) is type(1):

# 空序列爲false
== YES  ==>
if not seq:
if seq:

<== NO ==
if len(seq):
if not len(seq):