In the previous lesson, you learned that writing pseudocode can help you organize your thoughts and prepare yourself for writing code. You could write pseudocode anywhere, but you read that it can be helpful to have it right inside the file where you will write the code.
To make that possible, you have to write them as Python comments, with a # at the beginning of the line. You'll learn more about code comments in Python in this lesson.
Why Use Code Comments in Python
Python comments are exclusively for humans to read. Python completely ignores them. If you'd write your code only for a computer to execute, there would be no use for them at all. However, you nearly always write your code for humans.
You already learned that keeping track of your tasks with pseudocode can help while building a script. But there is more! While humans won't be the ones who execute the instructions, it's humans who do all the rest..
Advantages of Python Comments
- Understand: Humans have to be able to understand what's actually going on conceptually
- Maintain: Humans are the ones who need to maintain functionality over time and code changes
- Improve: Humans will try to improve what's there
- Extend: Humans will build on top of your code to create additional functionality
- Debug: Humans are the ones who dig into your codebase to fix bugs that come up inevitably
Writing descriptive code, as well as code comments where appropriate, is an important part of programming. You will learn more about what it means to write descriptive variable names in an upcoming lesson.
Writing code in a way that is easily readable should be your prime objective when writing code. Roaming online, you will encounter suggestions to "optimize" your code by choosing one-letter variables and decreasing the lines of code used in a script. However, a few milliseconds of a speed difference when executing your code rarely make a decisive difference. Instead, what does often make a difference are the hours and hours of developer time that can be saved if the code is well-written and easy to understand.
How To Write Python Comments
A basic Python code comment begins with a hashtag # and ends with a new line. This means that anything in a line that comes after a # will be part of a comment and therefore be disregarded by Python.
The following example shows a block comment followed by an inline comment:
# This whole line is a block comment
note = "This part is real code" # And the rest is an inline comment
Generally, it is encouraged to write block comments rather than inline comments unless the comment is extremely short. The pseudocode you wrote in the previous lesson was written as multiple block comments.
Think of your code as an essay and try to make it as pleasant to read as possible.
Info: You will learn more about variables and descriptive naming in a later lesson.
It is likely that either you or someone else will read your code later on. They will need to make sense of it. Keep that in mind while writing your code, and adopt good habits right from the beginning.
Additional Resources
- Zentut: Python Comments
- Digital Ocean: How to Write Comments in Python 3
- Coding Horror: Comments Tell You Why
Summary: Python Commenting
- Python comments, as well as code style, are for humans only. But that doesn't make them less important!
- Comments should explain why code was written the way it was
- Comments usually shouldn't explain how the code does something or what it does
- What the code does and how it accomplishes it should be self-explanatory through well-written code and descriptively named variables