#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 , 8 years ago
| Component: | Uncategorized → Core (Other) |
|---|---|
| Summary: | Fix comment style according to PEP → Fix comment verb style according to PEP 257 |
| Triage Stage: | Unreviewed → Accepted |
comment:2 by , 8 years ago
| Owner: | changed from to |
|---|---|
| Status: | new → assigned |
comment:3 by , 8 years ago
Here's a PR with work in progress. Made changes to one file.
Version 0, edited 8 years ago by (next)
comment:6 by , 8 years ago
| Patch needs improvement: | set |
|---|
A more careful review is required. I found many incomplete changes in the first commit.
comment:14 by , 8 years ago
| Resolution: | → fixed |
|---|---|
| Status: | assigned → closed |
Note:
See TracTickets
for help on using tickets.
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.