Docstrings

💡 Definition

• A special kind of string used in Python to document a module, class, function or method
• Written as a string literal, usually triple-quoted (””” or ''')
• Describe the purpose and behavior of the code they doument

💡 Characteristics

• Placement: A docstring should be the first statement in a module, class, method, or function.
• Accesbility: Docstrings can be accessed using the ‘__doc__’ attribute of the object they document.
• Style Guide: According to PEP 257, Docstrings should describe the method’s effect as a commannd, rather than as a description. They should use triple double-quotes for consistency, and the first line should be a short description.

💡 Examples

• Ex1. Documenting a Class

  class Animal:
      """
      A class used to represent an Animal.
  
      Attributes:
      name (str): The name of the animal.
      species (str): The species of the animal.
      age (int): The age of the animal in years.
      """
  
      def __init__(self, name, species, age):
          """
          The constructor for the Animal class.
  
          Parameters:
          name (str): The name of the animal.
          species (str): The species of the animal.
          age (int): The age of the animal in years.
          """
          self.name = name
          self.species = species
          self.age = age
  
      def make_sound(self, sound):
          """
          Makes the animal produce a sound.
  
          Parameters:
          sound (str): The sound that the animal makes.
  
          Returns:
          str: A string indicating the animal's sound.
          """
          return f'The {self.species} named {self.name} says {sound}'
  
  # Example of accessing docstrings
  print(Animal.__doc__)
  print(Animal.__init__.__doc__)
  print(Animal.make_sound.__doc__)

• Ex2. Documenting a Module

  """
  This module provides utilities for working with geometric shapes.
  
  Classes:
  - Circle: Represents a circle.
  - Square: Represents a square.
  
  Functions:
  - calculate_area: Calculates the area of a given shape.
  - calculate_perimeter: Calculates the perimeter of a given shape.
  """
  
  def calculate_area(shape):
      """
      Calculate the area of a given shape.
  
      Parameters:
      shape (Shape): The shape to calculate the area for.
  
      Returns:
      float: The area of the shape.
      """
      return shape.area()
  

💡 General Guidelines

• Triple Quotes: Always use triple double quotes(’ “”” ‘) for docstrings, even if the string fits on one line.
• First Line Summary: The first line should be a short summary of the object’s purpose. This should be a standalone summary that can be understood without reading further.
• Blank Line After Summary: If there are more details to provide, leave a blank line after the summary line. This helps separate the summary from the rest of the description.
• Detailed Description: Follow the summary with a more elaborate description if necessary. This part should provide additional details that help understand the behavior and purpose of the code.
• Indentation: Indent the docstring to align with the opening quotes.
• Imperative Mood: Use the imperative mood in the description. For example, say “Return the sum of x and y” instead of “Returns the sum of x and y.”