Python Docstrings

Documentation is hugely important, not just to communicate to other people what is the goal of a function/class/method/module, but also to yourself.

When you’ll come back to your code 6 or 12 months from now, you might not remember all the knowledge you are holding in your head, and reading your code and understanding what it is supposed to do, will be much more difficult.

Comments are one way to do so:

# this is a comment

num = 1 #this is another comment

Another way is to use docstrings.

The utility of docstrings is that they follow conventions and as such they can be processed automatically.

This is how you define a docstring for a function:

def increment(n):
    """Increment a number"""
    return n + 1

This is how you define a docstring for a class and a method:

class Dog:
    """A class representing a dog"""
    def __init__(self, name, age):
        """Initialize a new dog"""
        self.name = name
        self.age = age

    def bark(self):
        """Let the dog bark"""
        print('WOF!')

Document a module by placing a docstring at the top of the file, for example supposing this is dog.py:

"""Dog module

This module does ... bla bla bla and provides the following classes:

- Dog
...
"""

class Dog:
    """A class representing a dog"""
    def __init__(self, name, age):
        """Initialize a new dog"""
        self.name = name
        self.age = age

    def bark(self):
        """Let the dog bark"""
        print('WOF!')

Docstrings can span over multiple lines:

def increment(n):
    """Increment
    a number
    """
    return n + 1

Python will process those and you can use the help() global function to get the documentation for a class/method/function/module.

For example calling help(increment) will give you this:

Help on function increment in module
__main__:

increment(n)
    Increment
    a number

There are many different standards to format docstrings, and you can choose to adhere to your favorite one.

I like Google’s standard: https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings

Standard allows to have tools to extract docstrings and automatically generate documentation for your code.


This content originally appeared on flaviocopes.com and was authored by flaviocopes.com

Documentation is hugely important, not just to communicate to other people what is the goal of a function/class/method/module, but also to yourself.

When you’ll come back to your code 6 or 12 months from now, you might not remember all the knowledge you are holding in your head, and reading your code and understanding what it is supposed to do, will be much more difficult.

Comments are one way to do so:

# this is a comment

num = 1 #this is another comment

Another way is to use docstrings.

The utility of docstrings is that they follow conventions and as such they can be processed automatically.

This is how you define a docstring for a function:

def increment(n):
    """Increment a number"""
    return n + 1

This is how you define a docstring for a class and a method:

class Dog:
    """A class representing a dog"""
    def __init__(self, name, age):
        """Initialize a new dog"""
        self.name = name
        self.age = age

    def bark(self):
        """Let the dog bark"""
        print('WOF!')

Document a module by placing a docstring at the top of the file, for example supposing this is dog.py:

"""Dog module

This module does ... bla bla bla and provides the following classes:

- Dog
...
"""

class Dog:
    """A class representing a dog"""
    def __init__(self, name, age):
        """Initialize a new dog"""
        self.name = name
        self.age = age

    def bark(self):
        """Let the dog bark"""
        print('WOF!')

Docstrings can span over multiple lines:

def increment(n):
    """Increment
    a number
    """
    return n + 1

Python will process those and you can use the help() global function to get the documentation for a class/method/function/module.

For example calling help(increment) will give you this:

Help on function increment in module
__main__:

increment(n)
    Increment
    a number

There are many different standards to format docstrings, and you can choose to adhere to your favorite one.

I like Google’s standard: https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings

Standard allows to have tools to extract docstrings and automatically generate documentation for your code.


This content originally appeared on flaviocopes.com and was authored by flaviocopes.com


Print Share Comment Cite Upload Translate Updates
APA

flaviocopes.com | Sciencx (2021-01-19T05:00:00+00:00) Python Docstrings. Retrieved from https://www.scien.cx/2021/01/19/python-docstrings/

MLA
" » Python Docstrings." flaviocopes.com | Sciencx - Tuesday January 19, 2021, https://www.scien.cx/2021/01/19/python-docstrings/
HARVARD
flaviocopes.com | Sciencx Tuesday January 19, 2021 » Python Docstrings., viewed ,<https://www.scien.cx/2021/01/19/python-docstrings/>
VANCOUVER
flaviocopes.com | Sciencx - » Python Docstrings. [Internet]. [Accessed ]. Available from: https://www.scien.cx/2021/01/19/python-docstrings/
CHICAGO
" » Python Docstrings." flaviocopes.com | Sciencx - Accessed . https://www.scien.cx/2021/01/19/python-docstrings/
IEEE
" » Python Docstrings." flaviocopes.com | Sciencx [Online]. Available: https://www.scien.cx/2021/01/19/python-docstrings/. [Accessed: ]
rf:citation
» Python Docstrings | flaviocopes.com | Sciencx | https://www.scien.cx/2021/01/19/python-docstrings/ |

Please log in to upload a file.



There are no updates yet.
Click the Upload button above to add an update.

You must be logged in to translate posts. Please log in or register.

Related Posts