Commenting
When writing coding, you are not only writing for the computer. You are also communicating with people, namely you and other programmers looking at your code.
Therefore, it is good practice to leave comments in your code describing what you have done.
- For yourself in one year’s time: “What in the world was I trying to do here? Why did I write this for loop?”
- For other programmers trying to understand for your code: “I cannot understand the code. What in the world does this do? How am I going to fix this bug? Who wrote this pile of mess?!”
- For your lecturer: “Ok, I cannot understand what you are trying to do. And you did not leave any comments. Zero marks.”
All comments will be ignored by the Python interpreter. It is meant for humans to read.
In Python, you use a hash sign # to represent a comment. Anything after the # will be ignored by Python.
# Here is a comment.
# Here is another comment.
# Here is a third comment.
x = 5 # And you can write inline comments anywhere. But use this sparingly.
The level of detail of your comments depends on the context. If your code is self-explanatory, the comments can be a bit more high-level (“# searching for first time”), or can be used to provide some more details (“# n must be between 3-10”) or to explain the rationale behind why you did something (“# this loop here is to … this is also more efficient”). Basically, put yourself into the shoes of someone from the future trying to read your code. If it is not clear from your code, document it!
For example, this is too obvious:
x = x + 1 # Increment x
But this is more informative.
x = x + 1 # Compensate for border
Comments are also used to automatically generate documentations for your functions etc. For example, pydoc generates documentations from your code.
But writing # in front of every line is tedious! I have a LOT to say!
Officially, Python does not offer multi-line comments, like in C++ where you can surround your comments between /* and */.
However, you can exploit the fact that Python does not execute anything if you only provide an expression, like a string.
Try typing "this is a string" and save it as test.py and execute it with python3 test.py. You will not see anything executed. Remember that each line should be a statement, not just an expression. This will not work if you type the string into an interactive interpreter though!
So, as we discussed earlier, we can write multiline strings with triple quotes. So they can be used as comments since Python will read them but will not do anything with them.
'''
I am exploiting the fact that Python will not do anything
to me or reveal any of my juicy secrets.
Which is why I can type all I want and nobody running my
code will see me.
Multi-line comments for the win!
'''
print("This is what I show in public.")