我应该如何注释形状几乎不变的numpy.ndarray对象(Python)

Question

最近我注意到在脚本中留下注释或某种解释是多么重要。所以我决定在我的python脚本中添加注释来处理图像对象。

那么，我应该如何注释图像对象还是仅注释numpy.ndarray对象？我想澄清的是，功能的输入图像必须有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