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.
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.
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.
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.
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.
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.
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
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:
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__)
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