Opened 2 years ago

Closed 12 months 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 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:

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 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

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

comment:3 Changed 2 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 12 months ago by timo

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 12 months ago by aaugustin

  • Resolution set to wontfix
  • Status changed from new to closed

I agree with Tim.

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