Developer.com content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.
Commenting is an important and often overlooked aspect of computer programming that many developers tend to overlook early in their careers. Aside from being a part of best practices and standards, commenting code – also known as documenting – has many benefits to even the most veteran of coders. In this article, we look at the importance of documentation and how commenting works in Python.
Importance of Documenting Python Code
Why do we document our code? Isn’t commenting just a waste of time? We hear this from programmers on occasion, who assume that, if you know how to program in Python, you should have no trouble figuring out what the code you are looking at is supposed to do. Sounds simple right? After all, one of the benefits of learning to program in Python is that it is easy to learn and has a high level of readability, thanks in part to its English-like syntax.
However, as any seasoned developer will tell you, it is not always easy to figure out what, exactly, a snippet of code is intended for. For starters, as you develop your software, odds are you will need to revisit old modules and sections to update it as you add new features.
Sometimes the code that needs to be re-written was coded weeks, months, or even years ago. If you documented your code at that time – that is, wrote notes about what the code was intended to do – then you will have a much easier time knowing what you had intended to do and what your mindset was at the time. If not, you will find yourself banging your head trying to figure out your own logic.
As you grow as a programmer and begin to work on larger projects, you will likely be assigned to a team. That team of Python programmers will also need to view your code and work on it. Since every developer approaches coding differently, again, documenting your code becomes even more important.
Once again, these developers on your team – or worse, that take over for you after you leave – will not always be able to stroll over to your desk to ask what your code was meant to do or how it works. You or another developer will often be going over your old code at 3 o’clock in the morning or after a long day of staring at a computer monitor.
The point is this: commenting and documentation make it easier to understand your code and intentions. It makes your life – and every other developer looking at your work – much easier.
Single Line Commenting in Python
Comments are lines of text that Python ignores and does not consider part of a program. In a very real way, comments are invisible to the interpreter – a program that converts a high-level programming language such as Python into machine-readable code.
You can write a single line comment by starting with the hashtag – # – and following it with some text, as shown in the following example:
# This is a comment.
When Python encounters the #, it ignores all of the text that comes after it on that line. Once Python moves on to the next line, it begins reading once more, unless it encounters another hashtag, in which case the rules of commenting apply once more. Observe the following code:
# This is an example of a single-line comment. # It was written by James Payne
Python will read neither of the lines above. You can create multiple lines of comments by using a # on each concurrent line.
Inline Commenting in Python
Another way to comment in Python is to use inline commenting. This involves placing your comment after code. Here is an example of a program that will “print” text to the user’s window. Note the placement of our comment in this snippet:
print(“Hello Universe”) # This code prints the text “Hello Universe” to the user’s screen.
Anytime Python encounters a hashtag, it will ignore anything after it on that line, even if it shares a line with code.
One note about single line and inline comments: in general, as a best programming practice, PEP8 recommends programmers comment no more than 72 characters on a line. If your comment is longer, it is recommended that you make another single line comment to finish your thought.
Other Uses for Comments in Python
Comments can be used for other purposes than explaining what portions of your code are intended to do. They can also be a tool to layout future coding tasks within the portion of code you are working on. For example, let’s say you want to write several lines of code that print out several people’s names, but you do not know which names you want to print yet. You could use commenting to remind you to add these names later, like so:
# This is an amazing program that will print names print(“My name is James Payne”) print(“My father’s name is Ronnie Payne”) # Add another line to print out my father’s father’s name # once I figure out what it is
Another way you can use Python comments is to test your code. For example, if you are having trouble finding which line of code is causing an error or not working properly, you can always place a hashtag before a line of code to “comment it out”. This way, the Python interpreter will skip that line of code and move on to the next. This is a great, simple trick you can use if you want to test code or if you decide that portions of your code are no longer needed but do not want to erase those outdated snippets permanently.
Finally, when creating Python comments and documenting your code, try to remember to keep the comments short and precise. Avoid rambling or over-explaining. Try to practice proper grammar and use punctuation as you would if you were writing a real document. Also, avoid typing obvious comments. For example:
print(“Hello”) # A print statement print(“How are you?”) # Another print comment
Simple statements do not require a comment, and, in fact, commenting frivolously clutters up code and makes your work even sloppier.
