Documentation
Why is it important to document my code?
As you write code, it is extremely important that you keep some sort of documentation so that it makes it easier to interact with going forward. There are a number of different reasons why this benefits us a programmer.
It helps us, and others, understand our code
Well-documented code is easier to understand and maintain for both the original author and other developers who may work on the project in the future. Clear and concise documentation helps readers grasp the purpose, functionality, and usage of different code components, making it easier to navigate through the codebase.
It allows us to share knowledge between developers
Documentation serves as a means to transfer knowledge from one developer to another. When a project changes hands or a team member joins or leaves, thorough documentation ensures that the new developer can quickly get up to speed with the codebase, reducing the learning curve and minimizing the impact on productivity.
It makes it easier to collaborate on team projects
In collaborative software development, where multiple developers work on the same project, documentation facilitates effective collaboration. When different team members have a clear understanding of the code’s purpose, interfaces, and dependencies, they can work together more efficiently, avoiding conflicts and reducing the chances of introducing bugs or breaking existing functionality.
It makes it easier to debug
Well-documented code can expedite the debugging process and aid in issue resolution. By providing insights into the code’s behavior, expected inputs and outputs, and potential error scenarios, documentation enables developers to identify and fix issues faster. It serves as a reference point for troubleshooting and saves time that would otherwise be spent deciphering complex or poorly documented code.
It makes software easier to maintain
Software projects are not static; they evolve over time. Documentation allows developers to understand the original intent of the code and its design choices, making it easier to modify or extend functionality without introducing regressions. Well-documented code encourages good coding practices, such as modular design, code reusability, and separation of concerns, which contribute to maintainable and scalable software.
Comments
We have already seen the most common way that we can document our code: comments. In Python, you can make a comment by starting a line the #, and anything that comes after it on that line will be interpreted as a comment. This means that it will not affect the flow of the program, but is rather used as an easy way to make notes in the code to help the developer better understand it.
# This is a comment
age = 18 # I can also add comments at the end of a line of code
# I can describe what a function does using a comment
# This function prints out a birthday message
def birthday():
print("Happy birthday to you!")
# I can also leave comments over the course
# of multiple lines, as long as I start each
# one with a hashtag symbol
Docstrings
An additional, more formal way that we can document our code is by using docstrings, which is a description of a function that tells us more about what the function does. Docstrings appear right after the definition of a function, and are denoted using triple quotes.
def loanValue(principal, time, rate):
"""
Description: this function calculates the total value of a loan
Parameters (inputs):
principal (int): the borrowed amount of the loan
time (int): how many years on the loan
rate (float): the interest rate, represented as a decimal
Returns (output):
amount (float): the total value of the loan at the end of its life
"""
amount = principal * (1 + rate) ** time
return amount
# calculate the value of a loan worth $10000 at 3% over 5 years:
print(loanValue(10000, 5, 0.03)
Notice the information included in the docstring. While there are different protocols you may choose to use to write your docstring, generally it is good practice to include:
- A description of what the function does
- The input(s) provided
- The output returned
You can read more about some of the standard docstrings formats at the link here.
Once we have a docstring written, it is also possible to reference it by using the __doc__ attribute. For instance, if I wanted to print out the docstring of the function created above, I could write:
# This will display the docstring I wrote above:
print(loanValue.__doc__)
Generating Documentation Using pydoc
In addition to being able to access docstrings like we see above, we are also able to use the pydoc module to automatically generate documentation from Python modules. The documentation can be presented as pages of text on the console, served to a web browser, or saved to HTML files.
In the Shell tab on replit (not the Console), try typing the following command and click enter to view more documentation on the random module. You’ll be able to use the down arrow on your keyboard to scroll through the various descriptions, functions, and data that exist within that module. See if you can find some familiar functions, such as randint, choice, and shuffle.
python -m pydoc random
You can also explore other modules by changing the name provided at the end of the line above. Try commands like:
python -m pydoc math
python -m pydoc tuple
python -m pydoc pow