編碼風格#

注意

這完全複製自舊的 IPython wiki，目前正在開發中。本開發指南的許多資訊已過時。

本文件描述了我們的編碼風格。編碼風格指的是以下幾點

  • 原始碼的格式（縮排、空格等）

  • 事物的命名（變數、函式、類、模組等）

通用編碼約定#

通常，我們遵循 Python 官方風格指南 PEP 8 中描述的標準 Python 風格約定。

其他一般註釋

  • 在一個大檔案中，頂層類和函式之間應該用 2 行分隔，以便於視覺上區分它們。

  • 使用 4 個空格進行縮排，絕不使用硬製表符。

  • 在具有相同方法的類中保持方法的順序一致。這對於實現相似介面的類和相似的介面尤其如此。

命名約定#

對於命名約定，我們也遵循 PEP 8 的指導原則。一些現有程式碼未能完全遵循此原則，但對於所有新的和重構的 IPython 程式碼，我們將使用

  • 所有 小寫 模組名。長模組名可以使用下劃線分隔單詞（really_long_module_name.py），但這不是必需的。嘗試使用附近檔案的約定。

  • 類名使用 駝峰命名法（CamelCase）。

  • 方法、函式、變數和屬性使用 下劃線分隔小寫字母（lowercase_with_underscores）。

  • 特定於實現的私有方法將使用 _單下劃線字首（_single_underscore_prefix）。帶有雙下劃線字首的名稱只在特殊情況下使用，因為它們會使子類化變得困難（子類不易看到此類名稱）。

  • 偶爾會使用一些連字元小寫名稱，但主要用於非常短的名稱，或者當我們實現的方​​法與基類中現有方法非常相似時（例如 runlines()，其中 runsource() 和 runcode() 已經建立了先例）。

  • 舊的 IPython 程式碼庫中，類和模組名稱混雜著顯式的 IP 或 ip 字首。這並非必需，所有新程式碼都不應使用此字首。只有當類或函式預期要匯入到外部名稱空間中，並且其通用名稱（如 Shell）可能與其他名稱衝突時，這種方法才合理。但是，如果字首似乎絕對必要，則更傾向於使用更具體的 IPY 或 ipy。

  • 所有 JavaScript 程式碼也應遵循這些命名約定。

物件屬性宣告#

通常，物件應該在它們的類中宣告物件在其整個生命週期中將持有的所有屬性。雖然 Python 允許您在任何時間點向例項新增屬性，但這使得程式碼更難閱讀，並且要求方法不斷使用 hasattr() 檢查或 try/except 呼叫。透過在類頭中宣告物件的所有屬性，可以有一個地方來理解物件的資料介面，註釋可以解釋每個變數的作用，並且在可能的情況下，可以分配合理的預設值。

如果一個屬性旨在包含一個可變物件，它應該在類中設定為 None，並且其可變值應該在物件的建構函式中設定。由於類屬性由所有例項共享，未能做到這一點可能會導致難以跟蹤的錯誤。但是您仍然應該在類宣告中設定它，以便介面規範是完整的並在一個地方進行文件化。

一個簡單的例子

class Foo(object):
    # X does..., sensible default given:
    x = 1
    # y does..., default will be set by constructor
    y = None
    # z starts as an empty list, must be set in constructor
    z = None

    def __init__(self, y):
        self.y = y
        self.z = []

新檔案#

當為 IPython 啟動一個新的 Python 檔案時，您可以使用 以下模板 作為起點，其中已經為您預寫了一些常用內容。