Code is Confusing

Picture of a human looking confused, while a computer wearing a wizard hat looks happy.

Code can be confusing. There’s no way around it. Figuring out what a program does is often just as hard as writing the code in the first place — and sometimes harder. Bad code is so easy to write. Comments are a way for programmers to understand what a certain piece of code does without having to mentally translate it. Comments are written explanations embedded directly in the code that explain the code to the reader. The computer does not care about comments when it executes the code, and the system does not even look at the comments. They are only for humans to make code less confusing for other humans.

Comments in Python

print("This line is executed!")

# All the following lines are valid, because they're comments
# This line is not executed
# 1 / 0
# 5 = a

In Python, the main way to write comments is to use the “hash symbol” (#), also known as the “hashtag,” “octothorpe,” “number sign,” or “pound sign.” When Python runs your program, it first scans for any hash symbols. Those symbols and ALL text that comes after it on the same line are then removed. The only exception to this rule is if a comment is inside of a literal string value. Otherwise, comments are always removed from any Python program. You might be familiar with hashtags in social media that use the same ‘hash symbol’ as Python comments. Some example hashtags that you might find interesting are: #EveryoneCanCode, #CSforGood, #InclusiveCoding, and #CSforSocialJustice.

Tracing Comments

print("First line, first step.")
# Skipped line!
print("Third line, second step.")

Because commented code is removed from the program, Python will skip over those lines when running your code. This is one reason why, when tracing your program, the current line and the currently executed step might not be the same. In the program shown here, the second line is commented out, meaning the second step is actually the third line executed!

Improving Names to Avoid Comments

# Unclear variable names version
# Store the current time (42 minutes)
x = 42
# Convert to hours, add the offset
y = x / 60 + .5
# Print result
print(y)
# ----------------------------------------
# Clear variable names version
# Convert the time from minutes to hours, with an offset
minutes = 42
hours = minutes/60
offset = .5
time = hours + offset
print(time)

Comments aren’t always necessary. Sometimes, instead of trying to add additional explanations about code, you should just make the code less confusing. For example, in the code shown here, the first version uses variable names that are vague and confusing. But the second version has better variable names which make it easier to understand the code’s purpose. This is especially important as programs get bigger and more complex, where explaining every line has more of a penalty.

How Many Comments Are Enough?

How many comments should you write? Opinions vary, and there’s no perfect answer. Some people believe you should explain every line. Some people believe that comments should never be necessary, since you should just write the code to be clearer. A middle stance is to write comments for any code that is unexpected or surprising. When working with others or for someone, you will want to learn what their expectations are, while also developing your own style.

Commenting Out

minutes = 42
## Used to be integer division, now float division for correctness
# hours = minutes//60
hours = minutes / 60
offset = .5
time = hours + offset
print(time)

Comments can also be used to temporarily remove code. We call this “commenting out” code. However, permanently removing code using comments (instead of just deleting the code) is generally bad practice. In future courses, you will learn more advanced ways to keep track of code over time. But for now, when you are thinking about how to share code with others, remove any comments that don’t help explain the existing code. If you are going to comment out code, be sure to leave an additional comment for yourself explaining what that old code was there for. Remember, you are going to forget what a program does. The less time spent trying to remember, the better your future life will be.

Summary