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

  1. Python Introduction and Installation Guide
  2. Python Files and the Interpreter
  3. Experimenting With Numbers and Text In Python
  4. Python Variables
  5. Working With Number Variables In Python
  6. Python String Basics
  7. Advanced Python Strings
  8. Python Comments
  9. Python Lists
  10. Python List Methods
  11. Python Multidimensional Lists
  12. Python Tuples
  13. Python Boolean Operators
  14. Python If Statements
  15. Python While Loops
  16. Python For Loops
  17. Python Dictionaries
  18. Python Advanced Dictionaries
  19. Python Functions