[Django] #36500: pre-commit should enforce 79 char limit for docstrings and comments

Django

unread,

Jul 8, 2025, 9:58:56 PM7/8/25

to django-...@googlegroups.com

#36500: pre-commit should enforce 79 char limit for docstrings and comments
-------------------------------------+-------------------------------------
Reporter: Mike | Owner: Mike Edmunds
Edmunds |
Type: | Status: assigned
Cleanup/optimization |
Component: Packaging | Version: 5.2
Severity: Normal | Keywords:
Triage Stage: | Has patch: 0
Unreviewed |
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
-------------------------------------+-------------------------------------
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/36500>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

Django

unread,

Jul 8, 2025, 10:07:09 PM7/8/25

to django-...@googlegroups.com

#36500: pre-commit should enforce 79 char limit for docstrings and comments
-------------------------------------+-------------------------------------

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Mike Edmunds):

* has_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/36500#comment:1>

Django

unread,

Jul 9, 2025, 9:07:11 AM7/9/25

to django-...@googlegroups.com

#36500: pre-commit should enforce 79 char limit for docstrings and comments
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Owner: Mike
Type: | Edmunds
Cleanup/optimization | Status: assigned

Component: Documentation | Version: dev

Changes (by Jacob Walls):

* cc: David Smith (added)
* component: Packaging => Documentation
* version: 5.2 => dev

Comment:

To follow up on a question asked in the PR, the existing files are fixed
in https://github.com/django/django/pull/19549. There was some
[https://github.com/django/django/pull/19549#issuecomment-2993943017
discussion about pre-commit hooks] there as well. David, what do you think
of this proposal -- can flake8 handle the complexity I see in
`check_line_too_long_django()` in your PR?
--
Ticket URL: <https://code.djangoproject.com/ticket/36500#comment:2>

Django

unread,

Jul 9, 2025, 12:29:44 PM7/9/25

to django-...@googlegroups.com

#36500: pre-commit should enforce 79 char limit for docstrings and comments
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Owner: Mike
Type: | Edmunds
Cleanup/optimization | Status: assigned

Component: Uncategorized | Version: dev

Changes (by Mike Edmunds):

* component: Documentation => Uncategorized

Comment:

This issue is about the max line length for triple-quoted
`"""docstrings"""` and `# comment lines` in .py files in the django/ and
tests/ directories. (The PR Jacob linked is for reStructuredText .txt
files in the docs/ directory, which have a similar length restriction but
are otherwise unrelated to this issue. I'm not sure what the correct
category is, but it's not "Documentation".)

Right now, Django's Linters CI job and pre-commit checks enforce only the
88-char overall limit in .py files. The smaller 79-char limit for
docstrings and comments is enforced manually during PR review, if the
reviewer happens to notice it. This creates extra hurdles and noise for
both reviewers and contributors.

Unfortunately, the limit for docstrings and comments hasn't been
consistently enforced, and there are over 1300 cases where Django's
existing .py code doesn't comply with its own style requirements (see
https://github.com/django/django/pull/19627#issuecomment-3050890027).

So setting flake8 `max-doc-length = 79` would require fixing all those
exceptions first, or grandfathering them in (e.g., by listing the problem
files in .flake8 `per-file-ignores`).

An alternative might be adding `args: ["--max-docs-length=79"]` to the
flake8 section of pre-commit-config.yaml. That would make pre-commit
enforce the limit on modified files, without needing to address all the
existing violations. The downside is it only works for people who have
configured pre-commit, and the CI Linters job wouldn't catch the problem.
--
Ticket URL: <https://code.djangoproject.com/ticket/36500#comment:3>

Django

unread,

Jul 9, 2025, 2:53:20 PM7/9/25

to django-...@googlegroups.com

#36500: pre-commit should enforce 79 char limit for docstrings and comments
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Owner: Mike
Type: | Edmunds
Cleanup/optimization | Status: assigned
Component: Uncategorized | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Mike Edmunds):

Discussion: https://forum.djangoproject.com/t/enforce-or-eliminate-
comment-docstring-line-length-limit/41760
--
Ticket URL: <https://code.djangoproject.com/ticket/36500#comment:4>

Django

unread,

Jul 9, 2025, 9:57:20 PM7/9/25

to django-...@googlegroups.com

#36500: pre-commit should enforce 79 char limit for docstrings and comments
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Owner: Mike
Type: | Edmunds
Cleanup/optimization | Status: assigned
Component: Uncategorized | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Jacob Walls):

Appreciate the clarification: that was hasty of me to link that PR, as
well as to not check for related tickets first.

Previous discussion about auto-fixers for ''docstrings'' can be found
#25263 (`wontfix`/''Documentation''). (''Core(Other)'' also seems
reasonable, since we have other flake8 tickets there.) It might make sense
to treat this as a duplicate like #27668 pending the forum discussion
(thanks for starting one!)

> An alternative might be adding args: ["--max-docs-length=79"] to the

flake8 section of pre-commit-config.yaml (without changing the global
.flake8 config). That would make pre-commit enforce the limit on modified

files, without needing to address all the existing violations.

I doubt this would be workable, as it would format the whole file. (To me,
the practice of avoiding unrelated cosmetic changes is more important than
the line length.)
--
Ticket URL: <https://code.djangoproject.com/ticket/36500#comment:5>

Django

unread,

Jul 14, 2025, 8:03:46 AM7/14/25

to django-...@googlegroups.com

#36500: pre-commit should enforce 79 char limit for docstrings and comments
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Owner: Mike
Type: | Edmunds

Cleanup/optimization | Status: closed
Component: Uncategorized | Version: dev
Severity: Normal | Resolution: wontfix

Changes (by Sarah Boyce):

* resolution: => wontfix
* status: assigned => closed

Comment:

Given this is currently being discussed, we can reopen the ticket once
we've come to a conclusion
--
Ticket URL: <https://code.djangoproject.com/ticket/36500#comment:6>

Django

unread,

Jul 15, 2025, 1:33:35 PM7/15/25

to django-...@googlegroups.com

#36500: pre-commit should enforce 79 char limit for docstrings and comments
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Owner: Mike
Type: | Edmunds
Cleanup/optimization | Status: closed

Component: Core (Other) | Version: dev

Changes (by Natalia Bidart):

* component: Uncategorized => Core (Other)

--
Ticket URL: <https://code.djangoproject.com/ticket/36500#comment:7>

Reply all

Reply to author

Forward