Just a few weeks until the 2021 JavaScript Full-Stack Bootcamp opens.
Signup to the waiting list!
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.
The 2021 JavaScript Full-Stack Bootcamp will start at the end of March 2021. Don't miss this opportunity, signup to the waiting list!
More python tutorials:
- Introduction to Python
- Installing Python 3 on macOS
- Running Python programs
- Python 2 vs Python 3
- The basics of working with Python
- Python Data Types
- Python Operators
- Python Strings
- Python Booleans
- Python Numbers
- Python, Accepting Input
- Python Control Statements
- Python Lists
- Python Tuples
- Python Sets
- Python Dictionaries
- Python Functions
- Python Objects
- Python Loops
- Python Modules
- Python Classes
- The Python Standard Library
- Debugging Python
- Python variables scope
- Python, accept arguments from command line
- Python Recursion
- Python Nested Functions
- Python Lambda Functions
- Python Closures
- Python Virtual Environments
- Use a GoPro as a remote webcam using Python
- Python, how to create a list from a string
- Python Decorators
- Python Docstrings
- Python Introspection
- Python Annotations
- Python, how to list files and folders in a directory
- Python, how to check if a number is odd or even
- Python, how to get the details of a file
- Python, how to check if a file or directory exists
- Python Exceptions
- Python, how to create a directory
- Python, how to create an empty file
- Python, the `with` statement
- Python, create a network request
- Python, installing 3rd party packages using `pip`
- Python, read the content of a file
- Python, create a Web (HTTP) server
- Python, create a TCP server
- Python, how to write to a file
- Regular Expressions in Python
- Python List comprehensions
- Beginning GUI Programming in Python with `tkinter`
- How to install Pygame Zero on macOS
- How to check the current Python version
- Python Enums
- Python Constants
- Python Polymorphism
- Python Operator Overloading
- Python Ternary Operator
- The PEP8 Python style guide
- Introduction to multithreading in Python
- How to use Python map()
- How to use Python filter()
- How to use Python reduce()
- How to check if a variable is a string in Python
- How to check if a variable is a number in Python