Change to developer guide for docstring line length

dm-dev
Tags: #<Tag:0x00007ff62c129808>

(Tim Jenness) #1

We have just updated the developer guide to now include a specific directive on the line length of docstrings and comments in code. Previously 110 characters was used for all, but following the discussion on RFC-107 and the recent acceptance of a patch from @brianv0 to enable docstring length to be tested, which is something that PEP8 specifies, we are ready to adopt separate lengths for code and docstrings.

The new guideline is to use a maximum of 79 characters for docstrings. This is much closer to the numpydoc and PEP8 standards.

There is no need to drop everything to edit all your code. The suggestion is that you use the new limit when writing new docstrings/comments and when editing existing docstrings/comments. Most editors can be configured to use two rulers (at 79 and 110) to make it easy to see when a docstring is too long.

Flake8 does not yet support the new pycodestyle, but when it does the docstring length check will have to be enabled explicitly for each package when a package is compliant.