This short article will show you how to use comments in Python, including multi-line comments.
What is a Comment?
A comment in programing is one or more lines of text that aren’t interpreted as programming instructions. Instead, the computer skips them when executing your code, completely ignoring them. Therefore, comments don’t have to conform to any valid syntax. They’re just text that you read, and the computer doesn’t.
Single-Line Comments in Python
Comments in Python are any line that starts with a # (hash) character.
# This is a comment
It’s that simple. If the line begins with a hash, your computer will not read the text on that line on that code – it will be commented.
# This is a comment
print('This is not a comment')
Above, the first line is a comment. The second is not – as it doesn’t start with a #.
Multi-Line Comment Blocks in Python
Some programming languages have syntax for comments that span multiple lines. Python does not.
In other languages, multi-line comments have operators or symbols showing where a comment begins and ends, allowing them to cover multiple lines without prefixing every line with the comment symbol.
In Python, you just prefix every line with a #:
# Comment line 1 # Comment line 2 # Comment line 3
If for some reason, you don’t like how this looks, there is one other option – add a multi-line string and simply do not assign it to a variable.
It will appear in your code, but as it’s not assigned, the Python interpreter will discard it, and the contents will not be executed.
""" Comment line 1 Comment line 2 Comment line 3 """
Multi-line strings are wrapped in triple quotes.
This is not commenting syntax per se, but it achieves the same purpose.
Why Comment?
Extensive commenting is a good way to document your project and is overall good practice – here are a few reasons why.
Explain Yourself to Others
You might be the only developer on your project now – but what if it gets popular and you have to bring in someone else to help you maintain it and add features?
The reason why you coded something the way you did may not be obvious at first glance, or you might have had to put in a few clever workarounds to deal with a certain issue.
Leave a comment to make sure you aren’t leaving puzzles for your colleagues to solve.
Explain yourself… To Yourself
Ever look back on something you did months or years ago and wonder, “Why the hell did I do it that way?”?
Leave yourself a comment explaining why so you don’t have to rely on your memory.
For Documentation and Debugging
It’s common practice that for every function you have in your application, you should have a comment explaining how it should behave – what values it accepts and what values it should output.
This way, if you’re chasing a bug in your code, you can look at the comment which explains the function and double-check that the function is working as intended.
Leave Old/Buggy Code Behind
You can comment-out code, wrapping code that is no longer required in a comment so that it won’t be executed.
This is useful if you want to leave behind a reminder of how not to do something or if you have a bit of code that might be useful later but isn’t yet required. Put it in a comment for later.
