Location:this JIRA ticket
(This RFC is a re-scope of
RFC-106, which has been withdrawn.)
Our Python coding standard (https://confluence.lsstcorp.org/display/LDMDG/Python+Coding+Standard) states that
“Line Length MUST be less than or equal to 110 columns"
A consequence of this is that text in docstrings will also be wrapped at 110 characters.
I propose that we change our Python coding standard to state that any text extracted as user-facing documentation (such as docstrings) have a maximum line length of 79 characters.
This proposal is motivated by our goal to create an open source Python astronomy package with legacy value and broad adoption. Documentation is a key product that we deliver to users. Since our users are necessarily part of the Python astronomy community, we must appreciate the expectations that the Python community has for documentation. Users of open source Python expect <=79 character line lengths for docstrings when they ask for help in a Python terminal.
This norm, backed universally in the style guides of scientific python packages, originated for two reasons:
- These paragraphs are 150% wider than any typographer would dare typeset. Paragraphs this wide are hard to read, especially with the small leading (vertical line-to-line space) that most of us use in our code editors. 110-character wide doc paragraphs are bad for developers.
- Terminal-based Python help utilities do not reformat paragraphs, and instead show the docstring verbatim. Try help(numpy.array) in a Python terminal or numpy.array? in a Jupyter terminal/notebook. This means that all of our users will need to have terminals that are at least 110 characters wide. In the era of 13" laptop screens with tmux panes divided vertically three times, this isn't a reasonable thing to ask. 110-character wide doc paragraphs are bad for users.
The second reason is the one that our users, and there for I, care most deeply about. This RFC proposal strives to present our package as consistently as possible with other Python packages in the ecosystem.
Note that this RFC says nothing about the lengths of non-documentation lines in source. Nor does it say anything about the lengths of documentation lines in other languages such as C++ even if they may eventually become docstrings in Python.