Introduction
This guide isn’t about programming. In fact, there is no new code involved at all. However, it does have everything to do with making sure that the code that you write is understandable to both yourself and anyone else that might look at it down the line.
If you’ve looked at any open source projects, you’ve probably noticed notes placed in by the programmers. Those notes are just plain text. The programming language doesn’t compile or interpret them in any way. It just ignores them. It knows that those comments are for humans, not computers.
Comments are very important. Even if you aren’t sharing your code with anyone else, you will run into an instance where you look back at something that you wrote a long time ago and wonder, “What did I do here?” If you are interested in working on an open source project, which, chances are, you are, since you’re reading this on a Linux website, commenting is even more important. The last thing that you want is for your commit to be rejected because it’s not commented and the maintainer doesn’t want to waste time figuring out what it does. Comments are also important in system scripting. There very few single-person IT departments out there, and your coworkers aren’t going to be happy if they don’t know what’s going on in your scripts.
Commenting in Python
Like many other languages, Python has two different kinds of comments, single and multi line. Single line comments are excellent for adding a quick comment before a block of code or right after a line of code explaining what it does. Multi-line comments are useful for adding a header or a more detailed description to a piece of code. They are also great for commenting out a block of code so that it doesn’t run, which is great for debugging.
Single Line Comments
In Python, a single line comment begins with a #
. This is a fairly common symbol to use in scripting languages. Here’s an example of how you’d use a single line comment as a description.
a = 10 b = 15 a = b # Set a equal to b print( a + b )
The code will run exactly like it would if the comment wasn’t there. The comment is just there for you.
You can also use a single line comment to say what the next few lines of code will do.
# Import the Math library import math # Run the Pythagorean Theorem a = 3 b = 4 c = math.sqrt(a**2 + b**2)
Even though it’s a simple example that you could probably figure out jut by looking at it, the comments make looking at it much quicker. Imagine the time that would be saved on a more complex project.
Now, take a look at how you can use a single line comment to stop a line of code from running.
a = 10 b = 15 # a = b What happens if a isn't set equal to b print( a + b )
The line that set a
equal to b
didn’t run, giving a different result than the previous example
Multi-Line Comments
In Python, you can denote a multi-line comment by using """
before and after the code that you want to comment out. Of course, you can also use this for longer text comments like header information.
""" PYTHON TEST AUTHOR = Your Name LAST UPDATED = 1 November, 2016 PYTHON VERSION - 3.4.3 VERSION NUMBER = 1.0.0 """
None of that means anything to a computer, but it is excellent for documenting the progress of a project. Keeping information like that in project files doesn’t impact the actual program, but it enables you and anyone else working on the project to have quick and easy access to vital information. This is great for documenting collaborative projects with multiple files and multiple authors. Remember that most real-world projects will be complex, so documenting your code this way is a good habit to get into.
Multi-line comments are also essential for debugging. Say you just implemented a new feature to your project, but that new code is causing an error. You can comment out entire sections of it to test the new feature’s functionality piece by piece, until you finally find out where the problem is. Say the “Pythagorean Theorem” example from above was part of a feature that was failing. You could do something like the code below.
# Import the Math library import math """ FAILING - PLEASE DEBUG # Run the Pythagorean Theorem a = 3 b = 4 c = sqrt(a**2 + b**2) """
You can also use multi-line comments to stop an old piece of code while you replace it. Just deleting code isn’t usually the best practice. After all, once you delete it, it’s gone. Commenting out that code stops it from running, but also preserves it as a reference or fall-back just in case you need to look at it again.
Conclusion
Commenting code is important. That can’t be overstated. It may seem tedious and boring. It doesn’t have the flash of writing a new killer line that implements a feature, but in the long run, you’re going to be happy that those comments are there. Comments are also an invaluable debugging tool that can provide you with a solid procedure for testing out a failing piece of code. Keep practicing using comments and seeing how they can impact the flow of code when eliminating lines or blocks of code.
Table of Contents
- Python Introduction and Installation Guide
- Python Files and the Interpreter
- Experimenting With Numbers and Text In Python
- Python Variables
- Working With Number Variables In Python
- Python String Basics
- Advanced Python Strings
- Python Comments
- Python Lists
- Python List Methods
- Python Multidimensional Lists
- Python Tuples
- Python Boolean Operators
- Python If Statements
- Python While Loops
- Python For Loops
- Python Dictionaries
- Python Advanced Dictionaries
- Python Functions