PEP 8 - Style Guide for Python Code

本文參考Python PEP8所提出的風格指南與Google Python Style Guide

前言

Lab大多的專案都是以Python進行開發，尤其大多剛進來中心的同學都是先學Python，無論是第一組開發影像處理演算法或是第二組開發Web server、Socket等等。而在撰寫程式時，不知道你們有沒有發現一些怪怪的地方，像是: 程式碼排版、縮排、參數命名、註解寫法..等等，這些平常我們在’寫作’的風格，其實是有一系列規範的，其目的是在於使開發者可以寫出一系列可讀性高且風格一致的程式。

編排這些程式碼如同寫作，寫作需要了解讀句規則，寫程式也該清楚程式書寫風格，才得以在好的基礎下精進自我。

Python官方有一個編碼規範的風格指南: PEP 8 (Python Enhancement Proposal8)，上面有許多關於Python的用法建議。

讓我們開始吧!

PEP8程式碼編排規則

Basic

每行長度不超過79個字元
每行縮排4個空格
斷行字首與首行括號對齊
縮排使用空格而非Tab
判斷式或函式過長，使用反斜線``````斷行

1. import

import library時，import整個packages或modules，不單獨import types、classes或functions

import x  # import整個package或module
from x import y  # 從package或module import特定modules
from x import y as z  # 用法:

# 1. 有兩個同名的模組 y 需要導入
# 2. y 與目前模組中的頂級名稱衝突
# 3. y 與公共 API 中常用的參數名稱衝突（例如 features）
# 4. y 的名稱太長或太通用，不方便使用。

import錯誤範例

import a, b
import os, sys

2. 註解 (Comments):

Inline Comments: # 後空一格，註解與程式碼至少空兩隔
Documentation Strings
1. def之後才會出現
2. 結尾的”””會獨立一行

def add_numbers(a: int, b: int) -> int:
    """This is an example of adding two numbers.

    Args:
        a: first number
        b: second number

    Returns:
        The result of adding two numbers
    """
    return a + b

3. 縮排 (Code Lay-out)

正確範例

每層縮排4個空格
斷行字首與首行括號對齊

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

看得出var_three與var_one是對齊的吧!

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

首行沒有參數，次行垂直縮排，並且要比其他程式碼再加一層縮排。

錯誤範例

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

首行有參數。

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

次行對齊不能與其他程式碼在同一行，須再加一層縮排。

4. 多行括號

括號結束符與最後行的首字符對齊

my_list = [
    1, 2, 3,
    4, 5, 6,
    ]

括號結束符與首行的首字符對齊

my_list = [
    1, 2, 3,
    4, 5, 6,
]

5. 斷行

判斷式或函式過長，使用反斜線 \ 斷行

with open('/path/to/some/file/you/want/to/read') as file_1, \
    open('/path/to/some/file/being/written', 'w') as file_2:
    file_2.write(file_1.read())

6. 斷行時的操作符號

操作符號對齊

income = (gross_wages
            + taxable_interest
            + (dividends - qualified_dividends)
            - ira_deduction
            - student_loan_interest)

7. 表達式、語句中的空格

()、[]、{}等括號內不要有多餘空格
逗號、分號等符號前不用空格
括號內的運算符不用空格
調用函式時，key的括號前不用空格