我應該如何注釋形狀幾乎不變的 numpy.ndarray object (Python)

Question

最近我注意到在腳本中留下評論或某種解釋是多么重要。 所以我決定在我的 python 腳本中添加注釋來處理圖像 object。

那么，我應該如何注釋圖像 object 或只是 numpy.ndarray object？ 我想澄清 function 的輸入圖像必須有 3 個通道。

這是我當前的示例代碼。 但我不滿意。

def proc(image: numpy.ndarray) -> numpy.ndarray:
    print("hi")
    return image

對不起我的英語不好，請給我一些建議。

Answer 1

您的代碼應該是自記錄的，即遵循PEP 8中描述的命名和結構化約定。 類型提示和富有表現力的標識符名稱有助於推理您的代碼，但您不應僅限於此。 您可以在腳本中添加注釋和文檔字符串以添加更多信息。 可以使用特定的文檔字符串格式（reStructuredText、NumPy...），但您應該在整個項目中堅持使用相同的格式。

這是一個示例（遵循 NumPy 文檔字符串格式）：

def proc(image: numpy.ndarray) -> numpy.ndarray:
"""This function takes an input image, apply transformation X
and return the transformed image.

Parameters
----------
image : numpy.ndarray
    Input images must have 3 channels.

Returns
-------
numpy.ndarray
    The transformed image.
"""
    # processing code here with comments
    return image