Join us and get access to thousands of tutorials and a community of expert Pythonistas.
This lesson is for members only. Join us and get access to thousands of tutorials and a community of expert Pythonistas.
Python Commenting Best Practices and Tips
It is important to write comments that are readable and easy to understand. This lesson covers best commenting practices you can follow when writing code for yourself or for others. You’ll see how comments can be useful in breaking down problems into manageable parts, when debugging, and in making your code clearer for other developers.
The lesson also covers practices you should avoid when commenting, such as repeating yourself, code smells, and using rude comments.
00:00 Welcome back. Now it’s time to talk about commenting best practices. As we established earlier, commenting serves both you and others. When you comment your code, you do so to make your life easier.
00:15 The following best practices will help you achieve that goal. Creating an outline of your program in comments is a great way to start out, and it keeps your thoughts organized.
00:26 It also helps you visualize breaking down a problem into manageable parts. You may consider stepping through an algorithm or placing pseudo-code in comments as a placeholder for sections you’ll later translate into code.
00:41 Comments can be useful while debugging. You can comment out a selection of code you suspect is causing trouble or that you might want to rewrite. If you end up solving the problem, you can delete that faulty commented code and keep things tidy.
00:56 You can rely on version control if you should ever need to bring it back. You may also wish to incorporate comments if, say, you’ve introduced some complexity into your program.
01:07 Or you might be working with an unfamiliar module. Or you may have copied a code snippet from an online source. Or you could have simply patched things together in a less-than-optimal way.
01:20 In any of these cases, you’re helping yourself by describing in a comment what your code is doing, how it works, or the source you may have used.
01:31 There are additional considerations and best practices you should follow if you know that your code is going to be used and viewed by others. When your code is shared, others will likely depend on your comments as a guide to your project and an insight into how you think. It’s always great to have especially complicated functions explained.
01:53
Make sure you provide comments for that purpose. For public objects and functions, you’ll want to provide a docstring. Remember docstrings are surrounded by triple quotes (""") and are placed appropriately for the object that’s being documented—generally, right beneath the declaration. Once created, they will become the .__doc__ attribute’s value.
02:16 Module-level docstrings are also helpful. Anything a developer needs to know about your module should be explained here.
02:26 So there you have some examples of how to make it easier for others to read your code. So now we know what to do—let’s talk about what not to do.
02:37 In programming, you may have heard of the D.R.Y. principle. The D-R-Y in the word D.R.Y. stands for Don’t Repeat Yourself. It’s a good practice to eliminate redundancy in your code.
02:49 There’s a similar mantra related to commenting. Your comments should also be D.R.Y. But when we say comments should be D.R.Y., we also mean they shouldn’t be W.E.T.
03:00 So, the W-E-T in W.E.T. stands for Writing Everything Twice. Here’s an example.
03:08 The lesson here is if the code is clear on its own, let it be.
03:13 Up next, in our What Not To Do list is smelly comments. We want to avoid them. So, what is a smelly comment? The term code smells has been around for a while now, and it typically applies to code that is sloppy, hard to follow, and mostly inefficient.
03:32 Pretty comments can never fix ugly code. To avoid code smells, use descriptive variable names and practice the D.R.Y. principal. Try to write efficient, Pythonic code wherever possible.
03:45 Clean code doesn’t require excessive commenting. If you find yourself writing a lot of comments, take a step back and revisit your code. Up next in our Worst Practices list is rude comments.
03:59 It’s easy to forget sometimes that others might see your work. If you fall into this lazy trap, you may find yourself sprinkling some of your frustrations among your comments.
04:09 This is never a good idea. I speak from experience, ha. Keep it professional to save yourself embarrassment later. All right! That wraps up our best practices list and our worst practices list. Coming up in our next and final video, we’ll cover some techniques to get you started on commenting right now and we’ll wrap up everything we’ve learned.
Dan Bader RP Team on March 18, 2019
Captions would be appreciated
They’re coming! I can’t make any promises as to when exactly but they’re on my list. All courses will get full English captions.
victorariasvanegas on June 13, 2019
Hi @Daan Bader I would love a video course on using VIM for python developers, it looks very interesting, and the truth is that the tutorial on this page does not work very well.
ronaldoafonso on May 22, 2021
Very informative video. I didn’t care much about comments until I started working in a team. Now I can see how useful comments are even when you are working alone.
Pavneet Ghai on April 16, 2022
Hey Dan Bader, it would be helpful to see how to create docstrings for a module.
Bartosz Zaczyński RP Team on April 17, 2022
@Pavneet Ghai Have a look at the Package and Module Docstrings section of the tutorial about using docstrings in Python.
Become a Member to join the conversation.
Anonymous on March 14, 2019
Captions would be appreciated