Add additional style guidance for docstrings
|Reported by:||tga||Owned by:||nobody|
|Has patch:||no||Needs documentation:||no|
|Needs tests:||no||Patch needs improvement:||no|
Description (last modified by ptone)
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:
- 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 (5)
comment:1 Changed 2 years ago by tga
- Needs documentation unset
- Needs tests unset
- Patch needs improvement unset
- Resolution set to invalid
- Status changed from new to closed
comment:2 Changed 2 years ago by ptone
- Component changed from Uncategorized to Documentation
- Description modified (diff)
- Resolution invalid deleted
- Status changed from closed to new
- Summary changed from Better docstrings with parameter and return information to Add additional style guidance for docstrings
- Triage Stage changed from Unreviewed to Accepted
- Type changed from Uncategorized to Cleanup/optimization