Uploaded image for project: 'Request For Comments'
  1. Request For Comments
  2. RFC-107

Wrap python docstring text after 79 characters

    XMLWordPrintable

    Details

    • Type: RFC
    • Status: Implemented
    • Resolution: Done
    • Component/s: DM
    • Labels:
      None
    • Location:
      this JIRA ticket

      Description

      (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:

      1. 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.
      2. 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.

        Attachments

          Issue Links

            Activity

            Hide
            jsick Jonathan Sick added a comment -

            pycodestyle issue

            Show
            jsick Jonathan Sick added a comment - pycodestyle issue
            Hide
            jsick Jonathan Sick added a comment -

            To amplify the conclusion from DM-10448, which is the first story to implement an conversion of line lengths for existing Stack code:

            I have made a comment on https://github.com/PyCQA/pycodestyle/issues/344 about enabling separate lint check for comments/docstrings vs code. Have not had a reply yet but it might be worth adding to that issue.

            I think you are agreeing with me (at least as regards to this ticket) that autopep8 is not good enough for the task of fully automating this. These fixes took me an hour because I had to do a lot of manual tuning.

            It seems that implementing this RFC as-written isn't practical. Instead, a less disruptive path might be:

            1. Continue to allow <=110 character line lengths for Stack code (status quo).
            2. We (likely SQuaRE) submit a PR to pycodestyle and/or pydocstyle to permit separate line length rules for code and text (including comments and docstrings). This way we can maintain the best of both worlds: long code lines to accommodate the Science Pipelines coding style, and shorter lines of prose to promote readability in documentation paragraphs.
            3. We leverage the Travis flake8 checks that J Matt Peterson [X] is implementing for Stack repos. Initially all Stack repos will be tested against 110 line length limits. Then gradually repos will migrate to shorter lines for prose. We indicate that a repo has been converted to the RFC-107-style prose line length by adding a new rule to the repo's setup.cfg file. Both Travis and code editors capable of running flake8 error checking will automatically pick up on the rule.
            4. Again, we will never changed the 110 character line length for code; we only change the prose lengths, which is the original intent of this RFC.
            5. New codebases, like SQuaRE's, are free to be Pythonic today by putting 79 characters as the max line length in setup.cfg since 79 < 110, conforming to the existing guidelines.
            Show
            jsick Jonathan Sick added a comment - To amplify the conclusion from DM-10448 , which is the first story to implement an conversion of line lengths for existing Stack code: I have made a comment on https://github.com/PyCQA/pycodestyle/issues/344 about enabling separate lint check for comments/docstrings vs code. Have not had a reply yet but it might be worth adding to that issue. I think you are agreeing with me (at least as regards to this ticket) that autopep8 is not good enough for the task of fully automating this. These fixes took me an hour because I had to do a lot of manual tuning. It seems that implementing this RFC as-written isn't practical. Instead, a less disruptive path might be: Continue to allow <=110 character line lengths for Stack code (status quo). We (likely SQuaRE) submit a PR to pycodestyle and/or pydocstyle to permit separate line length rules for code and text (including comments and docstrings). This way we can maintain the best of both worlds: long code lines to accommodate the Science Pipelines coding style, and shorter lines of prose to promote readability in documentation paragraphs. We leverage the Travis flake8 checks that J Matt Peterson [X] is implementing for Stack repos. Initially all Stack repos will be tested against 110 line length limits. Then gradually repos will migrate to shorter lines for prose. We indicate that a repo has been converted to the RFC-107 -style prose line length by adding a new rule to the repo's setup.cfg file. Both Travis and code editors capable of running flake8 error checking will automatically pick up on the rule. Again, we will never changed the 110 character line length for code; we only change the prose lengths, which is the original intent of this RFC. New codebases, like SQuaRE's, are free to be Pythonic today by putting 79 characters as the max line length in setup.cfg since 79 < 110, conforming to the existing guidelines.
            Hide
            rowen Russell Owen added a comment -

            +! this sounds like a practical middle ground. I am still a bit leery of keeping docs short while leaving code long, but I think that will lead to more readable code than making everything short. Some editors provide support, e.g. by displaying multiple vertical guide lines (e.g. Sublime Text, Atom with a 3rd party extension), but others do not (e.g. BBEdit). I would be interested to what sort of support exists in emacs and vim.

            Show
            rowen Russell Owen added a comment - +! this sounds like a practical middle ground. I am still a bit leery of keeping docs short while leaving code long, but I think that will lead to more readable code than making everything short. Some editors provide support, e.g. by displaying multiple vertical guide lines (e.g. Sublime Text, Atom with a 3rd party extension), but others do not (e.g. BBEdit). I would be interested to what sort of support exists in emacs and vim.
            Hide
            jsick Jonathan Sick added a comment -

            In Vim:

            :set colorcolumn=79,110
            

            The PR to pycodestyle/pydocstyle is still necessary to make in-editor linters like flake8 (via Syntastic, for example, in Vim) most useful.

            Show
            jsick Jonathan Sick added a comment - In Vim: :set colorcolumn= 79 , 110 The PR to pycodestyle/pydocstyle is still necessary to make in-editor linters like flake8 (via Syntastic, for example, in Vim) most useful.
            Hide
            tjenness Tim Jenness added a comment -

            The developer guide has been updated to use 79 characters for docstrings and comments. Comments were included because the recent changes to pycodestyle to check for docstring line length also includes comments (following the PEP8 definition).

            Show
            tjenness Tim Jenness added a comment - The developer guide has been updated to use 79 characters for docstrings and comments. Comments were included because the recent changes to pycodestyle to check for docstring line length also includes comments (following the PEP8 definition).

              People

              Assignee:
              jsick Jonathan Sick
              Reporter:
              jsick Jonathan Sick
              Watchers:
              Chris Walter, Fritz Mueller, J Matt Peterson [X] (Inactive), John Parejko, John Swinbank, Jonathan Sick, Joshua Hoblitt, Kian-Tat Lim, Russell Owen, Tim Jenness
              Votes:
              1 Vote for this issue
              Watchers:
              10 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved:
                Planned End:

                  CI Builds

                  No builds found.