How should I annotate numpy.ndarray object whose shape is almost constant (Python)

Question

Recently I noticed how important leaving comment or some kind of explanation in script. So I decided to add annotation to my python script for processing image object.

Then, how should I annotate image object or just numpy.ndarray object? I want to clarify that input images for the function must have 3 channels.

Here is my current example code. But I'm not satisfied.

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

Sorry for my poor English, please give me some advices.

Answer 1

Your code should be self-documenting, ie following naming and structured conventions as described in PEP 8 . Type hinting and expressive identifier names help reason about your code but you should not be limited to that. You can add comments and docstrings to your script to add further information. There are specific docstrings formats that can be used (reStructuredText, NumPy...) but you should stick with the same format throughout your project.

Here is an example (following the NumPy docstring format):

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