Opened 12 years ago
Closed 10 years ago
#19907 closed Cleanup/optimization (wontfix)
Add additional style guidance for docstrings
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 (5)
comment:1 by , 12 years ago
Resolution: | → invalid |
---|---|
Status: | new → closed |
comment:2 by , 12 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 |
comment:3 by , 12 years ago
Ad-hoc (current)
def sql_destroy_indexes_for_fields(self, model, fields, style): """ Generates a SQL statement list with the DROP INDEX SQL statements for multiple model fields. `Style` object as returned by either color_style() or no_style() in django.core.management.color """
Sphinx Style
def sql_destroy_indexes_for_fields(self, model, fields, style): """ Generates the DROP INDEX SQL statements for multiple model fields. :param fields: Fields to generate SQL for :param style: `Style` object as returned by either color_style() or no_style() in django.core.management.color :returns: [SQL statement list] """
Google Style
def sql_destroy_indexes_for_fields(self, model, fields, style): """ Generates the DROP INDEX SQL statements for multiple model fields. Args: fields: Fields to generate SQL for style: `Style` object as returned by either color_style() or no_style() in django.core.management.color Returns: [SQL statement list] """
Suggestion: to avoid fluff, parameters should only be included in the docstring if they are actually documented.
comment:4 by , 10 years ago
I am in favor of continuing to use the current ad-hoc style. I find the other styles very verbose and distracting. Hopefully most code is simple enough that it doesn't need verbose docstrings.
I'm modifying the description and reopening this to target the improvement as something for the style guide