Commenting on your code are good methods if you want to help others understand what you have written. This makes it important to learn how to comment in Python if you work on a large team.
But it is also very important if you want to understand what you have written at some point in the future. Returning to old code can be disorienting, and this is a problem if you hope to offer ongoing support for an app.
Also read: How to use strings in Python
In this post, we will look at how to comment in Python and how we comment in a way that is logical and useful.
How to comment in Python and make it useful
The good news is that it’s extremely easy to comment in Python. You simply need to prefix what to write with a hashtag:
#This is a comment!
This way, everything you have written is ignored by the interpreter and will be marked for anyone who sees your code. You can place a Python comment either on its own line or even in line with the code you want to explain.
It’s easy to learn to comment in Python; it is difficult to know when to comment and how to ensure that these comments are readable and useful.
Also read: How to print in Python
One way to achieve this is by making sure your comments follow basic best practices. According to the Style Guide for Python Code, you should strive to keep your comments below 79 characters per line. This prevents the reader from having to scroll horizontally and keeps everything neat.
Although online comments can be useful, you should note that placing them in a row can make it difficult to know what is code and what is not – making it much more difficult to interpret the program in an instant.
This is confusing, for example:
if baddyX + 40 > mineX and baddyY + 40 > mineY and baddyX < mineX + 0 and baddyY < mineY + 19: #Checks the position of the bad guy in relation to the mine baddyX = 10000 #Sets the position of the bad guy to be far off the screen out of site pygame.display.update() #Updates the graphics reflecting the new positions for event in pygame.event.get(): #Looks for an event if event.type == pygame.QUIT: #If the event is the player clicking the cross run = False
A much better way to achieve something similar would be:
#If the baddy overlaps the mine, then the baddy is sent off page and the graphics update. Then we will check for events. if baddyX + 40 > mineX and baddyY + 40 > mineY and baddyX < mineX + 0 and baddyY < mineY + 19: baddyX = 10000 pygame.display.update() for event in pygame.event.get(): if event.type == pygame.QUIT: run = False
But of course, any of these would be an example of unnecessary comments!
When and how to comment in Python
As for comments ...
Some common and useful captions to add to your code include:
- A little about a new feature and what it does
- An explanation of what a variable or variable set is for
- Explain why you have done something in a certain way (if it is not obvious)
- Highlight key and important parts of your code
- Provide alerts
Some useful tips for keeping comments useful rather than distracting:
- Keep the comments concise and no longer necessary - respect your reader's time!
- Avoid comments that state the obvious; not over comment
- Do not just explain What something does: explain Why you put it there and why it is important
- Be polite and friendly! Do not use comments to embarrass other coders. It's a quick way to become the least popular person on your team.
More use for Python comments
The most important use for learning to comment in Python is to provide useful guidance and instruction. This can help others navigate the code. That said, there are other scenarios where using code can be useful.
Also read: How to create a file in Python and more
Headline comments, for example, go to the top of a file and can help explain what the code below does. This may even contain some useful instructions to help the reader find important features.
Headline comments can also be used as a place to insert a copyright notice or to explain your authorship of the code. Some people like to use ASCII to give their codes flamboyant titles.
Another use for Python comments is to help you quickly find your way around your code with the search tool. I will often leave comments so that I can quickly jump between different points in my code, or as a way to mark something I need to do later. If I leave something unfinished, I will often comment there so that I can easily find it again at a later time.
Finally, you can use comments in Python to make jokes. This will annoy some people and it will certainly not make your code as clean and efficient as possible. But personally? I think programming can be a lonely job, and sometimes finding a little wit or "hello" can lift your spirits.
It costs nothing to be nice!
Remember that knowing how to comment in Python does not excuse you from having to write clean, readable code. Your comments should serve as useful additional guidance for readers, not a Rosetta Stone to decode your crazy walks!
This means that you should also:
- Structure your code in a logical way
- Use smart names for variables and functions, along with a consistent naming convention
- By using new lines and impressions correctly (thankfully Python forces us to do this later)
There are those who believe that commenting code is actually an indication that the code was not well written to begin with. This audience is actually preaching against the use of comments altogether!
Ultimately, how sparingly or liberally you choose to comment on your code is a matter of personal preference. But keep in mind that someone looking at your code may not be as experienced as you, and a little guidance can be very helpful! The main goal is to make sure that everyone who needs to understand your code can, and as long as that is the case, it is up to you how you do it!
So that's how to comment in Python. What do you find useful / annoying when reading code? Is there something we missed? Let us know in the comments below!
If you want to learn more about Python coding, we recommend that you try an online course. This is the best way to quickly get hold of a new programming language. Check out our breakdown of the best options.