Unfortunately, only a few people want to write standalone technical documentation. Don't be upset; after years of development, software engineers found a handy shortcut. You can write documentation inside your block of code as comments at specific places. Doing it in this way, you can achieve three crucial benefits at the same time.
- By writing comments, you give yourself and your peers a clue about the purpose of your classes, functions, or even specific sections of code.
- Some IDEs can parse these comments and give you quick info about the function/class/module you will use.
- Special software allows you to generate documentation in HTML or PDF form and send it to anyone you need.
But remember that we are not talking about comments in general. We are talking about Python comments. They are special in the same way that anything is special in Python. So, let's finally learn about them!
The single-line comments are the most straightforward part of “code” you can write in Python.
To do so, you just use “#” and write your comment right after it.
This is also called a block comment (because it's on the same level as the code you're commenting on).
You can also write inline comments. Please remember a simple PEP-8 recommendation: Separate the piece of code and the # symbol with at least two spaces.
Now, even your grandmother (if she didn't know anything about programming) knows what this line is doing. Although, you might want to explain the “standard output” to her.
The crucial aspect of the #-comments is that an interpreter completely ignores them. So, if nothing stops you, you can comment your lines of code this way.
Note: even if I showed you this silly example, please keep your comments meaningful and valuable.
Python doesn't have a special syntax for multiline comments. You just need to use # for each line to leave this type of comment.
Remember that if you have multiple paragraphs, you should separate them by a new line with a single #.
Level up Python skills and advance your career
• Wide range of learning tracks for beginners and experienced developers
• Study at your own pace with your personal study plan
• Focus on practice and real-world experience