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.