Writing Readable Code
Introduction
Welcome back to Writing and Running Your First Python Programs! We are now stepping into the second lesson of the course, so we are officially building momentum.
In the previous lesson, we wrote our very first print() calls and watched Python display text and numbers on the screen. Those programs were short and easy to follow at a glance, but real programs grow longer very quickly, and our future selves (or a teammate) will thank us for leaving helpful notes along the way.
In this lesson, we will learn how to:
- Write comments with the
#symbol to explain what our code does. - Use a comment to temporarily disable a line of code.
- Keep our programs tidy with clear spacing so they are easy to read.
By the end, we will have a short greeting program that reads almost like a friendly note.
What Is a Comment?
Before we touch any code, let's build some intuition. A comment is a piece of text inside our program that Python completely ignores. It is not an instruction for the computer; it is a note for the humans reading the code.
In Python, comments start with the # symbol, sometimes called the hash or pound sign. Outside of quoted strings, everything after the # on that line is treated as a comment and ignored by Python. (Inside quotes, a # is just a normal character that belongs to the text, so print("# not a comment") really does print the #.) Here is our first look, using the opening of the program we will build:
Let's walk through what is happening:
- The first line begins with
#, so Python treats it as a note and does not run it. - The second line is a regular
print()call, which behaves exactly as we saw in the previous lesson.
Even though the comment produces no output, it tells any reader instantly what the program is about, which is a big win for clarity.
Commenting Out Code
There is a second, very practical use for #: placing it in front of a working line of code stops that line from running. Programmers call this commenting out the line, and it is handy when we want to temporarily hide some output without deleting the code.
Take a close look at the second line. On its own, print("Ask about our new loyalty card!") would be a perfectly valid instruction, but because we put a # at the very beginning, Python skips the entire line. Nothing gets printed.
Notice that the comment above it does not just repeat what the code says; it explains why the line is switched off (we are waiting for launch day). That kind of note is genuinely useful to a reader.
The nice thing is that the code remains right there in our file. If we later decide we want that message back, we simply remove the #, and the line springs back to life. This makes commenting out a great tool while testing or debugging, because we can toggle pieces of the program on and off without ever retyping them.
Adding Inline Comments
Comments do not have to live on their own line. We can also place them at the end of a line of code, right after the actual instruction. These are called inline comments.
Here is what to notice:
- The
print()call runs normally since it comes before the#. - Everything from the
#onward is ignored by Python, so# names today's featured drinkis just a note for us. - By convention, we leave two spaces between the end of the code and the
#, which keeps the line comfortable to read.
One quick note about good comments: the comments in this lesson are intentionally simple so we can focus on the syntax of writing them. In real programs, the most useful comments explain why something is done, or point out a tricky detail, rather than repeating what the code already makes obvious. As you write more code, aim for notes that add something a reader could not guess just by reading the line itself.
Keeping Code Readable with Spacing
Comments are only half of the readability story; blank lines are the other half. A well-placed empty line groups related instructions together, much like paragraphs group related sentences in a book. Let's look at the full program now:
Notice the three visual chunks separated by blank lines: the greeting, the disabled promo, and the daily special. When we run the file, Python skips every comment and every blank line, so only the two active print() calls produce output:
Only two lines of output are produced from a program that spans seven, yet the file remains clear at a glance. That is the payoff of good spacing and thoughtful comments.
Conclusion and Next Steps
In this lesson, we picked up three styles of comments in Python: a standalone comment on its own line, a commented-out line of code that we can quickly re-enable, and an inline comment placed at the end of a working line. We also saw how blank lines between logical chunks make a program feel calm and organized, even though Python itself ignores them completely.
None of these tools change what the program does, but every one of them changes how easy the program is to read. Up next is a short set of hands-on exercises where we will add, tweak, and remove comments, and tidy up spacing, in small programs of our own. Let's dive in and make some tidy code!
