Change the line length limit of docstrings to 88 characters #962
Description
We use the Black tool to format the code, and the default line length of Black is 88 characters. The 88-char line length limit is only applied to code, not docstrings. For docstrings, the line length limit is 79 characters, and we use several tools, blackdoc, docformatter and flake8 to check and format the docstrings.
Then, the question is, why do we use different line length limits for code and docstrings?
We started to adopt the 79-char line length limit for docstrings in PR #384. The PR description also explains why we choose 79-char length (also see some external discussions in fatiando/verde#177)
Jupyter, IPython, and other IDEs don't usually render the rst in the
docstrings and just show them literally. The problem is that many of
these break lines at 79 characters. So docstrings with more characters
look terrible in these settings and sometimes almost unreadable. Wrap
all docstrings to 79 characters instead of Black's 88.
Is the reason still valid?
I just changed one line of the docstrings of Figure.basemap() to ~120 chars, and checked what the docstrings look like in Jupyter, IPython, PyCharm, and VS Code. Here are the results:
In Jupyter Notebook, the long docstrings look good with the help() function:
Also look good in the Notebook Contextual Help page:
In a Python or IPython console:
In VS Code:
In PyCharm:
From the above screenshots, it's clear that these consoles, editors, and IDEs don't wrap docstrings at 80 characters and work well with long docstrings.
Now the questions are:
- Are they any other common editors or IDEs that force wrapping docstrings at 80 characters?
- Should we change the line length limit of docstrings to 88 characters?