Opened 4 years ago

Closed 2 years ago

#19907 closed Cleanup/optimization (wontfix)

Add additional style guidance for docstrings

Reported by: tga Owned by: nobody
Component: Documentation Version: master
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 Preston Holmes)

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 Changed 4 years ago by tga

Resolution: invalid
Status: newclosed

comment:2 Changed 4 years ago by Preston Holmes

Component: UncategorizedDocumentation
Description: modified (diff)
Resolution: invalid
Status: closednew
Summary: Better docstrings with parameter and return informationAdd additional style guidance for docstrings
Triage Stage: UnreviewedAccepted
Type: UncategorizedCleanup/optimization

I'm modifying the description and reopening this to target the improvement as something for the style guide

comment:3 Changed 4 years ago by tga

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 Changed 2 years ago by Tim Graham

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.

comment:5 Changed 2 years ago by Aymeric Augustin

Resolution: wontfix
Status: newclosed

I agree with Tim.

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