Opened 8 years ago

Closed 8 years ago

Last modified 7 years ago

#27656 closed Cleanup/optimization (fixed)

Fix comment verb style according to PEP 257

Reported by: Anton Samarchyan Owned by: Anton Samarchyan
Component: Core (Other) Version: dev
Severity: Normal Keywords:
Cc: desecho@… Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: yes
Easy pickings: yes UI/UX: no

Description

https://www.python.org/dev/peps/pep-0257/
The docstring is a phrase ending in a period. It prescribes the function or method's effect as a command ("Do this", "Return that"), not as a description; e.g. don't write "Returns the pathname ...".

It's also mentioned in the django code style.

Example from test/client.py - docstrings from two different functions.

"""
Send a TRACE request to the server.
"""
"""
Sets the Factory to appear as if it has successfully logged into a site.
"""

Change History (15)

comment:1 by Tim Graham, 8 years ago

Component: UncategorizedCore (Other)
Summary: Fix comment style according to PEPFix comment verb style according to PEP 257
Triage Stage: UnreviewedAccepted

I think it makes sense to do this rather than to continue explaining to new contributors about the preferred style (the "bad" style is often copied from existing code). Whoever works on this, please start small and send a work-in-progress pull request to make sure you're on the right track.

comment:2 by Anton Samarchyan, 8 years ago

Owner: changed from nobody to Anton Samarchyan
Status: newassigned

comment:3 by Anton Samarchyan, 8 years ago

Here's a PR with work in progress. Made changes to one file.

Version 0, edited 8 years ago by Anton Samarchyan (next)

comment:4 by Anton Samarchyan, 8 years ago

Has patch: set

I completed all of the changes.

comment:5 by Tim Graham <timograham@…>, 8 years ago

In 5411821e:

Refs #27656 -- Updated django.contrib docstring verb style according to PEP 257.

comment:6 by Tim Graham, 8 years ago

Patch needs improvement: set

A more careful review is required. I found many incomplete changes in the first commit.

comment:7 by Tim Graham <timograham@…>, 8 years ago

In 9718fa2e:

Refs #27656 -- Updated django.utils docstring verbs according to PEP 257.

comment:8 by Tim Graham <timograham@…>, 8 years ago

In 46960788:

Refs #27656 -- Updated django.template/tag docstring verbs according to PEP 257.

comment:9 by Tim Graham <timograham@…>, 8 years ago

In 3eb679a:

Refs #27656 -- Updated django.forms/http docstring verbs according to PEP 257.

comment:10 by Tim Graham <timograham@…>, 8 years ago

In 5a6f70b4:

Refs #27656 -- Updated django.core docstring verbs according to PEP 257.

comment:11 by Tim Graham <timograham@…>, 8 years ago

In 60e52a0:

Refs #27656 -- Updated django.db docstring verbs according to PEP 257.

comment:12 by Tim Graham <timograham@…>, 8 years ago

In 711123e1:

Refs #27656 -- Updated django.views docstring verbs according to PEP 257.

comment:13 by Tim Graham <timograham@…>, 8 years ago

In 86de930:

Refs #27656 -- Updated remaining docstring verbs according to PEP 257.

comment:14 by Tim Graham, 8 years ago

Resolution: fixed
Status: assignedclosed

comment:15 by Tim Graham <timograham@…>, 7 years ago

In ba76c3c:

Refs #27656 -- Removed "This will" prefix from djanog/templatetags/i18n.py docstrings.

Note: See TracTickets for help on using tickets.
Back to Top