# 4. 深入了解流程控制

除了剛才介紹的 `while`，Python 擁有在其他程式語言中常用的流程控制語法，並有一些不一樣的改變。

## 4.1. `if` 陳述式

或許最常見的陳述式種類就是 `if` 了。舉例來說：

    >>> x = int(input("Please enter an integer: "))
    Please enter an integer: 42
    >>> if x < 0:
    ...     x = 0
    ...     print('Negative changed to zero')
    ... elif x == 0:
    ...     print('Zero')
    ... elif x == 1:
    ...     print('Single')
    ... else:
    ...     print('More')
    ...
    More

在陳述式中，可以沒有或有許多個 `elif` 敘述，且 `else` 敘述並不是必要的。關鍵字 `elif` 是「else if」的縮寫，用來避免過多的縮排。一個 `if` ... `elif` ... `elif` ... 序列可以用來替代其他程式語言中的 `switch` 或 `case` 陳述式。

## 4.2. `for` 陳述式

在 Python 中的 `for` 陳述式有點不同於在 C 或 Pascal 中的慣用方式。相較於只能疊代 (iterate) 一個等差數列（如 Pascal），或給予使用者定義疊代步驟與終止條件（如 C），Python 的 `for` 陳述式疊代任何序列（list 或者字串）的元素，順序與它們出現在序列中的順序相同。例如（無意雙關）：

    >>> # Measure some strings:
    ... words = ['cat', 'window', 'defenestrate']
    >>> for w in words:
    ...     print(w, len(w))
    ...
    cat 3
    window 6
    defenestrate 12

在疊代一個集合的同時修改該集合的內容，很難獲取想要的結果。比較直觀的替代方式，是疊代該集合的副本，或建立一個新的集合：

    # Strategy:  Iterate over a copy
    for user, status in users.copy().items():
        if status == 'inactive':
            del users[user]

    # Strategy:  Create a new collection
    active_users = {}
    for user, status in users.items():
        if status == 'active':
            active_users[user] = status

## 4.3. `range()` 函式

如果你需要疊代一個數列的話，使用內建 `range()` 函式就很方便。它可以生成一等差數列：

    >>> for i in range(5):
    ...     print(i)
    ...
    0
    1
    2
    3
    4

給定的結束值永遠不會出現在生成的序列中；`range(10)` 生成的 10 個數值，即對應存取一個長度為 10 的序列內每一個項目的索引值。也可以讓 range 從其他數值開始計數，或者給定不同的公差（甚至為負；有時稱之為 step）：

    >>> list(range(5, 10))
    [5, 6, 7, 8, 9]

    >>> list(range(0, 10, 3))
    [0, 3, 6, 9]

    >>> list(range(-10, -100, -30))
    [-10, -40, -70]

欲疊代一個序列的索引值，你可以搭配使用 `range()` 和 `len()` 如下：

    >>> a = ['Mary', 'had', 'a', 'little', 'lamb']
    >>> for i in range(len(a)):
    ...     print(i, a[i])
    ...
    0 Mary
    1 had
    2 a
    3 little
    4 lamb

然而，在多數的情況，使用 `enumerate()` 函式將更為方便，詳見迴圈技巧。

如果直接印出一個 range 則會出現奇怪的輸出：

    >>> range(10)
    range(0, 10)

在很多情況下，由 `range()` 回傳的物件表現得像是一個 list（串列）一樣，但實際上它並不是。它是一個在疊代時能夠回傳所要求的序列中所有項目的物件，但它不會真正建出這個序列的 list，以節省空間。

我們稱這樣的物件為 iterable（可疊代物件），意即能作為函式及架構中可以一直獲取項目直到取盡的對象。我們已經了解 `for` 陳述式就是如此的架構，另一個使用 iterable 的函式範例是 `sum()`：

    >>> sum(range(4))  # 0 + 1 + 2 + 3
    6

待會我們可以看到更多回傳 iterable 和使用 iterable 為引數的函式。在資料結構章節中，我們會討論更多關於 `list()` 的細節。

## 4.4. 迴圈內的 `break` 和 `continue` 陳述式及 `else` 子句

`break` 陳述式，如同 C 語言，終止包含它的最內部 `for` 或 `while` 迴圈。

迴圈陳述式可以帶有一個 `else` 子句。當迴圈用盡所有的 iterable （在 `for` 中）或條件為假（在 `while` 中）時，這個子句會被執行；但迴圈被 `break` 陳述式終止時則不會執行。底下尋找質數的迴圈即示範了這個行為：

    >>> for n in range(2, 10):
    ...     for x in range(2, n):
    ...         if n % x == 0:
    ...             print(n, 'equals', x, '*', n//x)
    ...             break
    ...     else:
    ...         # loop fell through without finding a factor
    ...         print(n, 'is a prime number')
    ...
    2 is a prime number
    3 is a prime number
    4 equals 2 * 2
    5 is a prime number
    6 equals 2 * 3
    7 is a prime number
    8 equals 2 * 4
    9 equals 3 * 3

（沒錯，這是正確的程式碼。請看仔細：`else` 子句屬於 `for` 迴圈，並非 `if` 陳述式。）

當 `else` 子句用於迴圈時，相較於搭配 `if` 陳述式使用，它的行為與 `try` 陳述式中的 `else` 子句更為相似：`try` 陳述式的 `else` 子句在沒有發生例外 (exception) 時執行，而迴圈的 `else` 子句在沒有任何 `break` 發生時執行。更多有關 `try` 陳述式和例外的介紹，見處理例外。

`continue` 陳述式，亦承襲於 C 語言，讓所屬的迴圈繼續執行下個疊代：

    >>> for num in range(2, 10):
    ...     if num % 2 == 0:
    ...         print("Found an even number", num)
    ...         continue
    ...     print("Found an odd number", num)
    ...
    Found an even number 2
    Found an odd number 3
    Found an even number 4
    Found an odd number 5
    Found an even number 6
    Found an odd number 7
    Found an even number 8
    Found an odd number 9

## 4.5. `pass` 陳述式

`pass` 陳述式不執行任何動作。它可用在語法上需要一個陳述式但程式不需要執行任何動作的時候。例如：

    >>> while True:
    ...     pass  # Busy-wait for keyboard interrupt (Ctrl+C)
    ...

這經常用於建立簡單的 class（類別）：

    >>> class MyEmptyClass:
    ...     pass
    ...

`pass` 亦可作為一個函式或條件判斷主體的預留位置，在你撰寫新的程式碼時讓你保持在更抽象的思維層次。`pass` 會直接被忽略：

    >>> def initlog(*args):
    ...     pass   # Remember to implement this!
    ...

## 4.6. 定義函式 (function)

我們可以建立一個函式來產生費式數列到任何一個上界：

    >>> def fib(n):    # write Fibonacci series up to n
    ...     """Print a Fibonacci series up to n."""
    ...     a, b = 0, 1
    ...     while a < n:
    ...         print(a, end=' ')
    ...         a, b = b, a+b
    ...     print()
    ...
    >>> # Now call the function we just defined:
    ... fib(2000)
    0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597

關鍵字 `def` 介紹一個函式的定義。它之後必須連著該函式的名稱和置於括號之中的一串參數。自下一行起，所有縮排的陳述式成為該函式的主體。

一個函式的第一個陳述式可以是一個字串文本；該字串文本被視為該函式的說明文件字串，即 docstring。（關於 docstring 的細節請參見說明文件字串 (Documentation Strings)段落。）有些工具可以使用 docstring 來自動產生線上或可列印的文件，或讓使用者能以互動的方式在原始碼中瀏覽文件。在原始碼中加入 docstring 是個好慣例，應該養成這樣的習慣。

函式執行時會建立一個新的符號表 (symbol table) 來儲存該函式內的區域變數 (local variable)。更精確地說，所有在函式內的變數賦值都會把該值儲存在一個區域符號表。然而，在引用一個變數時，會先從區域符號表開始搜尋，其次為外層函式的區域符號表，其次為全域符號表 (global symbol table)，最後為所有內建的名稱。因此，在函式中，全域變數及外層函式變數雖然可以被引用，但無法被直接賦值（除非全域變數是在 `global` 陳述式中被定義，或外層函式變數在 `nonlocal` 陳述式中被定義）。

在一個函式被呼叫的時候，實際傳入的參數（引數）會被加入至該函式的區域符號表。因此，引數傳入的方式為傳值呼叫 (call by value)（這裡傳遞的值永遠是一個物件的參照 (reference)，而不是該物件的值）。1 當一個函式呼叫別的函式或遞迴呼叫它自己時，在被呼叫的函式中會建立一個新的區域符號表。

函式定義時，會把該函式名稱加入至當前的符號表。函式名稱的值帶有一個型別，並被直譯器辨識為使用者自定函式 (user-defined function)。該值可以被指定給別的變數名，使該變數名也可以被當作函式使用。這是常見的重新命名方式：

    >>> fib
    <function fib at 10042ed0>
    >>> f = fib
    >>> f(100)
    0 1 1 2 3 5 8 13 21 34 55 89

如果你是來自別的語言，你可能不同意 `fib` 是個函式，而是個程序 (procedure)，因為它並沒有回傳值。實際上，即使一個函式缺少一個 `return` 陳述式，它亦有一個固定的回傳值。這個值稱為 `None`（它是一個內建名稱）。在直譯器中單獨使用 `None` 時，通常不會被顯示。你可以使用 `print()` 來看到它：

    >>> fib(0)
    >>> print(fib(0))
    None

如果要寫一個函式回傳費式數列的 list 而不是直接印出它，這也很容易：

    >>> def fib2(n):  # return Fibonacci series up to n
    ...     """Return a list containing the Fibonacci series up to n."""
    ...     result = []
    ...     a, b = 0, 1
    ...     while a < n:
    ...         result.append(a)    # see below
    ...         a, b = b, a+b
    ...     return result
    ...
    >>> f100 = fib2(100)    # call it
    >>> f100                # write the result
    [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]

這個例子一樣示範了一些新的 Python 特性：

- `return` 陳述式會讓一個函式回傳一個值。單獨使用 `return` 不外加一個運算式作為引數時會回傳 `None`。一個函式執行到結束也會回傳 `None`。

- `result.append(a)` 陳述式呼叫了一個 list 物件 `result` 的 method（方法）。method 為「屬於」一個物件的函式，命名規則為 `obj.methodname`，其中 `obj` 為某個物件（亦可為一運算式），而 `methodname` 為該 method 的名稱，並由該物件的型別所定義。不同的型別定義不同的 method。不同型別的 method 可以擁有一樣的名稱而不會讓 Python 混淆。（你可以使用 class（類別）定義自己的物件型別和 method，見 Class（類別））範例中的 `append()` method 定義在 list 物件中；它會在該 list 的末端加入一個新的元素。這個例子等同於 `result = result + [a]`，但更有效率。

## 4.7. 深入了解函式定義

定義函式時使用的引數 (argument) 數量是可變的。總共有三種可以組合使用的形式。

### 4.7.1. 預設引數值

為一個或多個引數指定預設值是很有用的方式。函式建立後，可以用比定義時更少的引數呼叫該函式。例如：

    def ask_ok(prompt, retries=4, reminder='Please try again!'):
        while True:
            ok = input(prompt)
            if ok in ('y', 'ye', 'yes'):
                return True
            if ok in ('n', 'no', 'nop', 'nope'):
                return False
            retries = retries - 1
            if retries < 0:
                raise ValueError('invalid user response')
            print(reminder)

該函式可以用以下幾種方式被呼叫：

- 只給必要引數：`ask_ok('Do you really want to quit?')`

- 給予一個選擇性引數：`ask_ok('OK to overwrite the file?', 2)`

- 給予所有引數：`ask_ok('OK to overwrite the file?', 2, 'Come on, only yes or no!')`

此例也使用了關鍵字 `in`，用於測試序列中是否包含某個特定值。

預設值是在函式定義當下，於定義時的作用域中求值，所以：

    i = 5

    def f(arg=i):
        print(arg)

    i = 6
    f()

將會輸出 `5`。

重要警告：預設值只求值一次。當預設值為可變物件，例如 list、dictionary（字典）或許多類別實例時，會產生不同的結果。例如，以下函式於後續呼叫時會累積曾經傳遞的引數：

    def f(a, L=[]):
        L.append(a)
        return L

    print(f(1))
    print(f(2))
    print(f(3))

將會輸出：

    [1]
    [1, 2]
    [1, 2, 3]

如果不想在後續呼叫之間共用預設值，應以如下方式編寫函式：

    def f(a, L=None):
        if L is None:
            L = []
        L.append(a)
        return L

### 4.7.2. 關鍵字引數

函式也可以使用關鍵字引數，以 `kwarg=value` 的形式呼叫。舉例來說，以下函式：

    def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):
        print("-- This parrot wouldn't", action, end=' ')
        print("if you put", voltage, "volts through it.")
        print("-- Lovely plumage, the", type)
        print("-- It's", state, "!")

接受一個必要引數 (`voltage`) 和三個選擇性引數 (`state`，`action`，和 `type`)。該函式可用下列任一方式呼叫：

    parrot(1000)                                          # 1 positional argument
    parrot(voltage=1000)                                  # 1 keyword argument
    parrot(voltage=1000000, action='VOOOOOM')             # 2 keyword arguments
    parrot(action='VOOOOOM', voltage=1000000)             # 2 keyword arguments
    parrot('a million', 'bereft of life', 'jump')         # 3 positional arguments
    parrot('a thousand', state='pushing up the daisies')  # 1 positional, 1 keyword

但以下呼叫方式都無效：

    parrot()                     # required argument missing
    parrot(voltage=5.0, 'dead')  # non-keyword argument after a keyword argument
    parrot(110, voltage=220)     # duplicate value for the same argument
    parrot(actor='John Cleese')  # unknown keyword argument

函式呼叫時，關鍵字引數 (keyword argument) 必須在位置引數 (positional argument) 後面。所有傳遞的關鍵字引數都必須匹配一個可被函式接受的引數（`actor` 不是 `parrot` 函式的有效引數），而關鍵字引數的順序並不重要。此規則也包括必要引數，（`parrot(voltage=1000)` 也有效）。一個引數不可多次被賦值，下面就是一個因此限制而無效的例子：

    >>> def function(a):
    ...     pass
    ...
    >>> function(0, a=0)
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    TypeError: function() got multiple values for argument 'a'

當最後一個參數為 `**name` 形式時，它接收一個 dictionary（字典，詳見 映射类型 --- dict），該字典包含所有可對應形式參數以外的關鍵字引數。`**name` 可以與 `*name` 參數（下一小節介紹）組合使用，`*name` 接收一個 tuple，該 tuple 包含一般參數以外的位置引數（`*name` 必須出現在 `**name` 前面）。例如，若我們定義這樣的函式：

    def cheeseshop(kind, *arguments, **keywords):
        print("-- Do you have any", kind, "?")
        print("-- I'm sorry, we're all out of", kind)
        for arg in arguments:
            print(arg)
        print("-" * 40)
        for kw in keywords:
            print(kw, ":", keywords[kw])

它可以被如此呼叫：

    cheeseshop("Limburger", "It's very runny, sir.",
               "It's really very, VERY runny, sir.",
               shopkeeper="Michael Palin",
               client="John Cleese",
               sketch="Cheese Shop Sketch")

輸出結果如下：

    -- Do you have any Limburger ?
    -- I'm sorry, we're all out of Limburger
    It's very runny, sir.
    It's really very, VERY runny, sir.
    ----------------------------------------
    shopkeeper : Michael Palin
    client : John Cleese
    sketch : Cheese Shop Sketch

注意，關鍵字引數的輸出順序與呼叫函式時被提供的順序必定一致。

### 4.7.3. 特殊參數

在預設情況，引數能以位置或明確地以關鍵字傳遞给 Python 函式。為了程式的可讀性及效能，限制引數的傳遞方式是合理的，如此，開發者只需查看函式定義，即可確定各項目是按位置，按位置或關鍵字，還是按關鍵字傳遞。

函式定義可能如以下樣式：

    def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):
          -----------    ----------     ----------
            |             |                  |
            |        Positional or keyword   |
            |                                - Keyword only
             -- Positional only

`/` 和 `*` 是選擇性的。這些符號若被使用，是表明引數被傳遞給函式的參數種類：僅限位置、位置或關鍵字、僅限關鍵字。關鍵字參數也稱為附名參數 (named parameters)。

#### 4.7.3.1. 位置或關鍵字引數 (Positional-or-Keyword Arguments)

若函式定義中未使用 `/` 和 `*` 時，引數可以按位置或關鍵字傳遞給函式。

#### 4.7.3.2. 僅限位置參數 (Positional-Only Parameters)

此處再詳述一些細節，特定參數可以標記為僅限位置。若參數為僅限位置時，它們的順序很重要，且這些參數不能用關鍵字傳遞。僅限位置參數必須放在 `/`（斜線）之前。`/` 用於在邏輯上分開僅限位置參數與其餘參數。如果函式定義中沒有 `/`，則表示沒有任何僅限位置參數。

`/` 後面的參數可以是位置或關鍵字或僅限關鍵字參數。

#### 4.7.3.3. 僅限關鍵字引數 (Keyword-Only Arguments)

要把參數標記為僅限關鍵字，表明參數必須以關鍵字引數傳遞，必須在引數列表中第一個僅限關鍵字參數前放上 `*`。

#### 4.7.3.4. 函式範例

請看以下的函式定義範例，注意 `/` 和 `*` 記號：

    >>> def standard_arg(arg):
    ...     print(arg)
    ...
    >>> def pos_only_arg(arg, /):
    ...     print(arg)
    ...
    >>> def kwd_only_arg(*, arg):
    ...     print(arg)
    ...
    >>> def combined_example(pos_only, /, standard, *, kwd_only):
    ...     print(pos_only, standard, kwd_only)

第一個函式定義 `standard_arg` 是我們最熟悉的形式，對呼叫方式沒有任何限制，可以按位置或關鍵字傳遞引數：

    >>> standard_arg(2)
    2

    >>> standard_arg(arg=2)
    2

第二個函式 `pos_only_arg` 的函式定義中有 `/`，因此僅限使用位置參數：

    >>> pos_only_arg(1)
    1

    >>> pos_only_arg(arg=1)
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    TypeError: pos_only_arg() got some positional-only arguments passed as keyword arguments: 'arg'

第三個函式 `kwd_only_args` 的函式定義透過 `*` 表明僅限關鍵字引數：

    >>> kwd_only_arg(3)
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    TypeError: kwd_only_arg() takes 0 positional arguments but 1 was given

    >>> kwd_only_arg(arg=3)
    3

最後一個函式在同一個函式定義中，使用了全部三種呼叫方式：

    >>> combined_example(1, 2, 3)
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    TypeError: combined_example() takes 2 positional arguments but 3 were given

    >>> combined_example(1, 2, kwd_only=3)
    1 2 3

    >>> combined_example(1, standard=2, kwd_only=3)
    1 2 3

    >>> combined_example(pos_only=1, standard=2, kwd_only=3)
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    TypeError: combined_example() got some positional-only arguments passed as keyword arguments: 'pos_only'

最後，請看這個函式定義，如果 `**kwds` 內有 `name` 這個鍵，可能與位置引數 `name` 產生潛在衝突：

    def foo(name, **kwds):
        return 'name' in kwds

呼叫該函式不可能回傳 `True`，因為關鍵字 `'name'` 永遠是連結在第一個參數。例如：

    >>> foo(1, **{'name': 2})
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    TypeError: foo() got multiple values for argument 'name'
    >>>

使用 `/`（僅限位置引數）後，就可以了。函式定義會允許 `name` 當作位置引數，而 `'name'` 也可以當作關鍵字引數中的鍵：

    def foo(name, /, **kwds):
        return 'name' in kwds
    >>> foo(1, **{'name': 2})
    True

換句話說，僅限位置參數的名稱可以在 `**kwds` 中使用，而不產生歧義。

#### 4.7.3.5. 回顧

此用例決定哪些參數可以用於函式定義：

    def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):

說明：

- 如果不想讓使用者使用參數名稱，請使用僅限位置。當參數名稱沒有實際意義時，若你想控制引數在函式呼叫的排列順序，或同時使用位置參數和任意關鍵字時，這種方式很有用。

- 當參數名稱有意義，且明確的名稱可讓函式定義更易理解，或是你不希望使用者依賴引數被傳遞時的位置時，請使用僅限關鍵字。

- 對於應用程式介面 (API)，使用僅限位置，以防止未來參數名稱被修改時造成 API 的中斷性變更。

### 4.7.4. 任意引數列表 (Arbitrary Argument Lists)

最後，有個較不常用的選項，是規定函式被呼叫時，可以使用任意數量的引數。這些引數會被包裝進一個 tuple 中（詳見 Tuples 和序列 (Sequences)）。在可變數量的引數之前，可能有零個或多個普通引數：

    def write_multiple_items(file, separator, *args):
        file.write(separator.join(args))

Normally, these variadic arguments will be last in the list of formal parameters, because they scoop up all remaining input arguments that are passed to the function. Any formal parameters which occur after the `*args` parameter are 'keyword-only' arguments, meaning that they can only be used as keywords rather than positional arguments.

    >>> def concat(*args, sep="/"):
    ...     return sep.join(args)
    ...
    >>> concat("earth", "mars", "venus")
    'earth/mars/venus'
    >>> concat("earth", "mars", "venus", sep=".")
    'earth.mars.venus'

### 4.7.5. 拆解引數列表（Unpacking Argument Lists）

當引數們已經存在一個 list 或 tuple 裡，但為了滿足一個需要個別位置引數的函式呼叫，而去拆解它們時，情況就剛好相反。例如，內建的 `range()` 函式要求分開的 start 和 stop 引數。如果這些引數不是分開的，則要在呼叫函式時，用 `*` 運算子把引數們從 list 或 tuple 中拆解出來：

    >>> list(range(3, 6))            # normal call with separate arguments
    [3, 4, 5]
    >>> args = [3, 6]
    >>> list(range(*args))            # call with arguments unpacked from a list
    [3, 4, 5]

同樣地，dictionary（字典）可以用 `**` 運算子傳遞關鍵字引數：

    >>> def parrot(voltage, state='a stiff', action='voom'):
    ...     print("-- This parrot wouldn't", action, end=' ')
    ...     print("if you put", voltage, "volts through it.", end=' ')
    ...     print("E's", state, "!")
    ...
    >>> d = {"voltage": "four million", "state": "bleedin' demised", "action": "VOOM"}
    >>> parrot(**d)
    -- This parrot wouldn't VOOM if you put four million volts through it. E's bleedin' demised !

### 4.7.6. Lambda 運算式

`lambda` 關鍵字用於建立小巧的匿名函式。`lambda a, b: a+b` 函式返回兩個引數的和。Lambda 函式可用於任何需要函數物件的地方。在語法上，它們被限定只能是單一運算式。在語義上，它就是一個普通函式定義的語法糖 (syntactic sugar)。與巢狀函式定義一樣，lambda 函式可以從包含它的作用域中引用變數：

    >>> def make_incrementor(n):
    ...     return lambda x: x + n
    ...
    >>> f = make_incrementor(42)
    >>> f(0)
    42
    >>> f(1)
    43

上面的例子用 lambda 運算式回傳了一個函式。另外的用法是傳遞一個小函式當作引數：

    >>> pairs = [(1, 'one'), (2, 'two'), (3, 'three'), (4, 'four')]
    >>> pairs.sort(key=lambda pair: pair[1])
    >>> pairs
    [(4, 'four'), (1, 'one'), (3, 'three'), (2, 'two')]

### 4.7.7. 說明文件字串 (Documentation Strings)

以下是關於說明文件字串內容和格式的慣例。

第一行都是一段關於此物件目的之簡短摘要。為保持簡潔，不應在這裡明確地陳述物件的名稱或型別，因為有其他方法可以達到相同目的（除非該名稱剛好是一個描述函式運算的動詞）。這一行應以大寫字母開頭，以句號結尾。

文件字串為多行時，第二行應為空白行，在視覺上將摘要與其餘描述分開。後面幾行可包含一或多個段落，描述此物件的呼叫慣例、副作用等。

Python 剖析器 (parser) 不會去除 Python 中多行字串的縮排，因此，處理說明文件的工具應在必要時去除縮排。這項操作遵循以下慣例：在字串第一行之後的第一個非空白行決定了整個說明文件字串的縮排量（不能用第一行的縮排，因為它通常與字串的開頭引號們相鄰，其縮排在字串文本中並不明顯），然後，所有字串行開頭處與此縮排量「等價」的空白字元會被去除。不應出現比上述縮進量更少的字串行，但若真的出現了，這些行的全部前導空白字元都應被去除。展開 tab 鍵後（通常為八個空格），應測試空白字元量是否等價。

下面是多行說明字串的一個範例：

    >>> def my_function():
    ...     """Do nothing, but document it.
    ...
    ...     No, really, it doesn't do anything.
    ...     """
    ...     pass
    ...
    >>> print(my_function.__doc__)
    Do nothing, but document it.

        No, really, it doesn't do anything.

### 4.7.8. 函式註釋 (Function Annotations)

函式註釋是選擇性的元資料（metadata）資訊，描述使用者定義函式所使用的型別（更多資訊詳見 PEP 3107 和 PEP 484）。

註釋以 dictionary（字典）的形式存放在函式的 `__annotations__` 屬性中，且不會影響函式的任何其他部分。參數註釋的定義方式是在參數名稱後加一個冒號，冒號後面跟著一個對註釋求值的運算式。回傳註釋的定義方式是在參數列表和 `def` 陳述式結尾的冒號中間，用一個 `->` 文字接著一個運算式。以下範例註釋了一個必要引數、一個選擇性引數，以及回傳值：

    >>> def f(ham: str, eggs: str = 'eggs') -> str:
    ...     print("Annotations:", f.__annotations__)
    ...     print("Arguments:", ham, eggs)
    ...     return ham + ' and ' + eggs
    ...
    >>> f('spam')
    Annotations: {'ham': <class 'str'>, 'return': <class 'str'>, 'eggs': <class 'str'>}
    Arguments: spam eggs
    'spam and eggs'

## 4.8. 間奏曲：程式碼風格 (Coding Style)

現在你即將要寫更長、更複雜的 Python 程式，是時候討論一下編碼樣式了。大多數語言都能以不同的樣式被書寫（或更精確地說，被格式化），而有些樣式比其他的更具可讀性。能讓其他人輕鬆閱讀你的程式碼永遠是一個好主意，而使用優良的編碼樣式對此有極大的幫助。

對於 Python，大多數的專案都遵循 PEP 8 的樣式指南；它推行的編碼樣式相當可讀且賞心悅目。每個 Python 開發者都應該花點時間研讀；這裡是該指南的核心重點：

- 用 4 個空格縮排，不要用 tab 鍵。

  4 個空格是小縮排（容許更大的巢套深度）和大縮排（較易閱讀）之間的折衷方案。Tab 鍵會造成混亂，最好別用。

- 換行，使一行不超過 79 個字元。

  換行能讓使用小顯示器的使用者方便閱讀，也可以在較大顯示器上並排陳列多個程式碼檔案。

- 用空行分隔函式和 class（類別），及函式內較大塊的程式碼。

- 如果可以，把註解放在單獨一行。

- 使用說明字串。

- 運算子前後、逗號後要加空格，但不要直接放在括號內側：`a = f(1, 2) + g(3, 4)`。

- Class 和函式的命名樣式要一致；按慣例，命名 class 用 `UpperCamelCase`（駝峰式大小寫），命名函式與 method 用 `lowercase_with_underscores`（小寫加底線）。永遠用 `self` 作為 method 第一個引數的名稱（關於 class 和 method，詳見 初見 class）。

- 若程式碼是為了用於國際環境時，不要用花俏的編碼。Python 預設的 UTF-8 或甚至普通的 ASCII，就可以勝任各種情況。

- 同樣地，若不同語言使用者閱讀或維護程式碼的可能性微乎其微，就不要在命名時使用非 ASCII 字元。

註解

1

  實際上，傳址呼叫 (call by object reference) 的說法可能較為貼切。因為，若傳遞的是一個可變物件時，呼叫者將看得見被呼叫者對物件做出的任何改變（例如被插入 list 內的新項目）。