What is the proper way to comment functions in Python?

Deep dive into docstring best practices

Writing docstrings that sing

Forget about providing a bland function summary. Turn your docstrings into a detailed manual. Inform users of the expected inputs, return values, side effects, and exceptions that they should anticipate because surprises are for birthday parties, not code!

Show, don’t tell – with doctests

Why limit yourself to telling users how your function works? Show them with doctests inside your docstrings. They serve a dual purpose: they educate your users and keep your code in check as simple unit tests:

def add(a, b):
    """
    Add 'a' to 'b'. 

    Disclaimer: Does not work with apples and oranges.
    :param a: First addend of the equation. 
    :param b: Second addend of the equation.
    :return: Result of 'a' + 'b'. 

    >>> add(2, 3)
    5
    """
    return a + b


Shouting from the rooftops with Sphinx

Once you've got robust docstrings, tools like Sphinx can then convert them into beautifully formatted documentation. That's a win-win!

Picking your docstring length

Is your function more like a tweet or Tolstoy's War and Peace? Use multi-line docstrings for complex functions and save single-line docstrings for those self-explanatory one-liners:

def is_even(number):
    """Enter a number and this will tell you if it's even. Spoiler: it's a coin toss."""
    return number % 2 == 0


Unleashing the power of docstrings

Leverage interactive help features

Write thoughtful docstrings and you'll get more out of Python's help() function. It spares you the "what was this function again?" head-scratching.

help(multiply)


Keep it clean

Overflowing your function bodies with hash pylint marks (# pylint: disable=) is the code equivalent of covering your white shirt with spaghetti sauce. Keep it clean!

Clarity above all else

It's a function, not a whodunit. Note expected context and preconditions. If your function expects a certain environment or preexisting conditions, state them clearly.

Less is more

Yes, ASCII art can be fun, but consider it dessert, not the main meal. Stick to a clean, simple, and easy-to-read style. This isn't an arts and crafts project.

The philosophy of good docstring writing

Let your language do the talking

Be a tour guide, not a mechanic. Highlight the higher-level behavior of your function. Keep the nitty-gritty implementation details in your code, not your docstrings.

Shed light on assumptions

Remember good old show and tell? If your function assumes a certain system state or dependency, tell it upfront. This ensures that later, it can show its best performance.

Refer to conventions

We can't reinvent the wheel in every project. For larger ones with numerous modules, consistency is key. PEP 258, Sphinx, and PyCharm conventions can help maintain a consistent docstring style across the board.