Summary line in Python’s docstring – Everyday Coder's Blog

Tips and no tricks.

Summary line in Python’s docstring

My company uses a tool similar to pylint to enforce coding standard for our Python codebase. Today it gave the following error when I tried adding comments to a method:

Line 33: Docstring summary should be on one line and followed by a blank line.

I looked it up and to my surprise, it is an official convention written in PEP 0257:

Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description. The summary line may be used by automatic indexing tools; it is important that it fits on one line and is separated from the rest of the docstring by a blank line.

Quite unusual in my opinion. I occasionally find it difficult having to summarize what a function does in a single line (80 characters).

I searched in popular Python projects such as numpy or cpython and observed that even though most of their code are following this convention, there are a quite number of exceptions, for example: here, here, and here. In contrast, Some Python projects like django just don’t care about this convention at all. We can spot exceptions pretty much in every source file.

I decided to write a short and inadequate comment to move my pull request forward. Will revisit when I come across a better solution.

Leave a Reply

Your email address will not be published. Required fields are marked *