Comments in code provide a way for you to leave notes to yourself and others about what your code does. These are very useful, if not essential, in a team setting. The term code documentation in general refers to the set of comments in source code that, hopefully, explain something about that code.
Code documentation is a double-edged sword. Done well, it helps you and others understand your code. Done poorly, it provides no value and can even mislead. Further, code documentation needs to be updated when the code is updated!
We want our code documentation to be clear and concise, just like the code itself. Here is what we will focus on documenting.
You can apply these rules to almost any language you encounter, and you will find that the recommendations for creating class and function comments different per language.
Self-documenting code is a popular term for “I can look at the code and understand it’s purpose.” How do you achieve that?
Use descriptive variable, function, and class names according to your team’s coding conventions.
Variables and classes should be nouns that describe the data.
max
, min
, sum
.for name in birds:
where birds
is a list of strings.total = sum(scores)
Functions should be verbs or start with a verb. They should describe what the function does.
compute_average_score()
. In Java, you would use camelCaseIn-line comments are useful but should not be abused. Use in-line comments to:
Do not write a comment for every line. A programmer proficient in the programming language should be able to understand your code if you use good variable names and your logic is clear. In cases where the logic is unclear or convoluted, a code comment is warranted to explain your implementation.
In Python, we document modules (.py
files), classes, and functions with docstrings. Docstrings are part of the Python language syntax.
IDEs like PyCharm and Visual Studio Code look for docstrings to provide information about a module, class, or function:
On the first line of the file, put something similar to the following:
"""This module contains functions useful for counting birds."""
That’s it. You can add multi-line docstrings where needed like so:
|
|
You do the same thing for classes. Provide a short summary just below the class name:
|
|
Place a blank line below the function name and type """
. PyCharm will prepare a template for you.
def __init__(self, name: str, age: int, height: float, weight: float):
"""
:param name:
:param age:
:param height:
:param weight:
"""
self.name = name
self.age = age
self.height = height
self.weight = weight
PyCharm’s docstring template understands the following:
:param <name>
for you to describe purpose of each parameter if you have them.:return:
for you to describe what your function returns, if anything.:raises <ErrorType>:
Where you can manually enter the various Exceptions your function might raise.Fill in the contents like so.
def __init__(self, name, age, weight, height):
"""
Class constructor.
:param name: the patient's full name
:param age: age in whole years
:param height: height in inches
:param weight: weight in pounds
"""
self.name = name
self.age = age
self.height = height
self.weight = weight
Now with your docstrings set up, you will see helpful pop-ups in your IDE when you type class and function names!
sum
a bad variable name?doc()
a bad function name?compute_risk()
function.calculate_area()
that takes a list
of numbers as its only parameter. If there are three elements in the list, compute and return the area of a triangle (assume it is a right triangle). If there are two elements, return the area of a rectangle. Otherwise, raise a ValueError
.param:
values, and a raises:
value.