Why use Comments?

Let me ask you a question. Do you remember all the things you did in the afternoon, specifically after 1:47 PM of May 19'th of last year? Well, unless something significant happened that day, you probably don't remember.

But if I were to ask you for the details anyhow, you probably would try to remember it, ask your friends/family, look up your phone for a picture, chat, text messages. But they don't always guarantee that you would be able to reproduce the facts of that day, which is a problem.

Suppose you are a sole developer working on a complicated project with many intricate details spanning hundreds of modules and thousands of lines; a change in a particular function is required. If you have not written that function recently, it would be difficult for you to recall what you achieved, your methodology, your thought process when you did whatever you did. If you won't remember it, your best bet is to go through the function again, understand it, and reach a conclusion.

Now, in doing so, how much time will you spend? Probably a lot, and as a sole developer, time is of paramount importance.

Now, if you could document the details of the function explaining its working, you would immediately understand and make changes. Thereby, save time and enhance your productivity. Commenting on your code is the same as maintaining a diary entry or a daily journal.

Documentation is a vital part of software engineering. As a software developer, make it a habit to document your code as much as possible with relevant details.

Keep these points handy:

• The programmer can use comments to describe the logical reasoning behind the code.
• Comments help make the code more readable and understandable for the programmer.
• The programmer can use comments to provide other details, such as Contact Details.
• The interpreter will omit comments when processing the source code.

---

Creating a Comment

Python supports only a single type of Comment, i.e., Single-Line comment. Single Line comments start with a Hash character ('#').

However, you can also use multi-line strings as multi-line comments. Multi-line comments are enclosed within """ or ''' (three double or single quotes).

---

What to comment and what not to?

Let us look at an example and determine what makes a comment helpful and relevant.

The #1 comment is irrelevant since we already are in the module and are aware of it, it provides no meaningful information, and adds to the clutter. Hence, it should not be a part of the documentation.

The #2, #3, and #4 comments are helpful as they can be of use if you decide to have other developers working on the project to get informed when the code was written and who to contact if any assistance is required.

The #5 and the #6 comments describe choosing a 32 character key instead of a 16 or 24 one.

The #7 comment is irrelevant since the length of the key has no relevance with the encryption mode selected. Instead, the programmer must document such details near the function responsible for performing cryptography.

Always keep comments as near as possible to the relevant code, preferably just above it. However, when in doubt about anything, you must always document it and mark it as "unclear" to make the reader aware that few details could be of less or no significance.

---

Conclusion

This chapter taught us the importance of documentation while developing software, the pitfalls of not doing so, documenting Python code, two types of comments available, how Python processes comments, and elements of a well-documented comment.