Opened 11 years ago
Last modified 10 years ago
#19907 closed Cleanup/optimization
Add additional style guidance for docstrings — at Version 2
| Reported by: | tga | Owned by: | nobody |
|---|---|---|---|
| Component: | Documentation | Version: | dev |
| Severity: | Normal | Keywords: | comments |
| Cc: | Triage Stage: | Accepted | |
| Has patch: | no | Needs documentation: | no |
| Needs tests: | no | Patch needs improvement: | no |
| Easy pickings: | no | UI/UX: | no |
Description (last modified by )
Many functions need better parameter documentation in their docstring because without it, it is difficult to understand what's going on.
https://docs.djangoproject.com/en/1.4/internals/contributing/writing-code/coding-style/ contains some basic guidance on docstrings, but nothing about if, when, or how arguments and return values are documented.
Google provides one such style guide which has been popularly adopted:
http://google-styleguide.googlecode.com/svn/trunk/pyguide.html#Comments
Benefits include:
- it provides a standard way of writing docstrings,
- it will also help with IDE and interactive shell support.
- Helps people reading the source code.
Change History (2)
comment:1 by , 11 years ago
| Resolution: | → invalid |
|---|---|
| Status: | new → closed |
comment:2 by , 11 years ago
| Component: | Uncategorized → Documentation |
|---|---|
| Description: | modified (diff) |
| Resolution: | invalid |
| Status: | closed → new |
| Summary: | Better docstrings with parameter and return information → Add additional style guidance for docstrings |
| Triage Stage: | Unreviewed → Accepted |
| Type: | Uncategorized → Cleanup/optimization |
Note:
See TracTickets
for help on using tickets.
I'm modifying the description and reopening this to target the improvement as something for the style guide