Re: [Django] #36500: inconsistent 79 char limit for docstrings and comments (was: pre-commit should enforce 79 char limit for docstrings and comments)

[Django]

#36500: inconsistent 79 char limit for docstrings and comments
------------------------------+----------------------------------------
Reporter: Mike Edmunds | Owner: Mike Edmunds
Type: Bug | Status: new
Component: Core (Other) | Version: dev
Severity: Normal | Resolution:
Keywords: flake8 | Triage Stage: Unreviewed
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
------------------------------+----------------------------------------
Changes (by Mike Edmunds):

* keywords: => flake8
* resolution: wontfix =>
* status: closed => new
* summary: pre-commit should enforce 79 char limit for docstrings and
comments => inconsistent 79 char limit for docstrings and comments
* type: Cleanup/optimization => Bug


Old description:

> Django's coding style has long required
> [https://docs.djangoproject.com/en/5.2/internals/contributing/writing-
> code/coding-style/#python-
> style:~:text=We%20allow%20up%20to%2088%20characters%20as%20this%20is%20the%20line%20length%20used%20by%20black.%20This%20check%20is%20included%20when%20you%20run%20flake8.%20Documentation%2C%20comments%2C%20and%20docstrings%20should%20be%20wrapped%20at%2079%20characters%2C%20even%20though%20PEP%208%20suggests%2072.
> limiting docstrings and comments] to 79 characters, while allowing a
> larger 88-char limit for code lines. (The latter matches Black's
> default.)
>
> Currently, only the 88 char limit is enforced by pre-commit linting, via
> flake8. The 79 char limit is manually enforced during PR review.
>
> Early versions of flake8 supported only a single `max-line-length ` limit
> that applied to both code and comments/docstrings. flake8 3.7.8
> (2019-07-08) added a separate `max-doc-length` configuration option.
>
> Django should set that option so reviewers and contributors don't need to
> spend time cycling on line length.

New description:

Django's coding style has long required
[https://docs.djangoproject.com/en/5.2/internals/contributing/writing-code
/coding-style/#python-
style:~:text=We%20allow%20up%20to%2088%20characters%20as%20this%20is%20the%20line%20length%20used%20by%20black.%20This%20check%20is%20included%20when%20you%20run%20flake8.%20Documentation%2C%20comments%2C%20and%20docstrings%20should%20be%20wrapped%20at%2079%20characters%2C%20even%20though%20PEP%208%20suggests%2072.
limiting docstrings and comments] to 79 characters, while allowing a
larger 88-char limit for code lines. (The latter matches Black's default.)

But a large number of files in Django's source code have docstrings and
block comments with lines that are between 80–88 characters long,
violating this coding standard.

Currently, only the 88 char limit is enforced by pre-commit linting, via
flake8. The 79 char limit is (sometimes) manually enforced during PR
review.

Early versions of flake8 supported only a single `max-line-length ` limit
that applied to both code and comments/docstrings. flake8 3.7.8
(2019-07-08) added a separate `max-doc-length` configuration option.

Django should either automatically enforce (via flake8 and pre-commit)
this requirement or remove it so reviewers and contributors don't need to
spend time cycling on line length.

[Edited to clarify discrepancy between existing coding standard and
existing code.]

--
Comment:

The consensus in the forum discussion seems to be to remove the separate
79-char limit for docstrings and comments.

There's also a strong argument for keeping the requirement and bringing
the existing code in compliance so it can be enforced by flake8.

I've opened PRs for both options. (The second one is, naturally, quite a
bit more complicated. It would require some additional manual reformatting
and careful review/merge coordination.)
--
Ticket URL: <https://code.djangoproject.com/ticket/36500#comment:8>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.