As long as your codes are not solely for your personal use, and some other person will read or maintain them, you cannot do without comments in programming.
Even if your program is for your use only, it’s easy to get lost in the ideas behind the codes that you have written after some time. With nicely written comments, you can easily refresh your memory.
If you are in a team or writing programs that another person will read, maintain or make use of their own programs, it’s a good practice to include comments.
Comments not only make your codes more readable but also makes it easy for others to get along with them quickly.
Perhaps, in future when you are not around, these comments will be there to provide clarifications.
While it is a good idea to write comments in your programs, it can be a nightmare and a source of confusion if not properly done. Littering your programs with irrelevant comments is worse than no comments at all.
In this post, I will be sharing how tips that will help you to write good comments.
What are comments in programming
Comments are a piece of non-executable text that explains what a program or piece of code does. They describe what a program does and how it does it.
Comments are meant to be read by humans and are ignored by the compiler. Comments are not executable and are ignored by the compiler or interpreter when the program is run.
For someone who is not familiar with the programming language, comments help such a person understand what the program does.
Comments in Python programming
The hash symbol # is used to indicate a comment in Python programming. Any line of code preceded by this symbol is considered a comment.
A comment that extends beyond a line is called a multiline comment. This kind of comment can be made by enclosing the text in triple single or double quotes. Texts in the triple single or double quotes are called docstrings and are extensively used for documentation purposes.
#single line comment
For multiline comments:
""" multiline comments or comments that span across multiple pages """
What’s the right way to comment
Commenting is a good practice only if you do it well. Some write comments to make their line of code look longer. Others forget to remove codes that were commented out.
Knowing how to write comments is one thing but writing them well is another thing. The essence of comments is to provide clarity to your program. If you must comment, then you must do it right.
Here are important things to keep in mind while writing comments.
Conventions in writing comments
By convention, comments are provided at the beginning of a program describing the program, the author and the license information.
Also, end comments are can be provided at the end of the statement. This kind of comment is called an end-of-line comment.
#Author: Bona Akubue #(c) 2023 #This code is licensed under MIT license
The following tips will help you write better comments.
1. Make it plain and simple
The comments you leave in your programs explain the code even when you are not around. For this reason, you must keep it simple and straight to the point. Make it easy to understand.
Any comment that would end up stressing others should be scrapped.
2. Don’t litter your codes with comments
Some programmers write comments because they were told that it is good practice. A lot of times, they do it the bad way. They litter their codes with unnecessary and confusing comments, which defeats the essence of it.
Ensure that you do not litter your codes with unnecessary comments that do provide useful information.
Good comments shouldn’t be vague and meaningless pieces of text. They are meant to provide clarity to programs, and not confusion.
Also, avoid writing comments for every single line of code. Most times, they are completely useless.
3. Write comments before the actual codes
It is recommended that you write comments even before the actual codes. Writing comments before the actual codes give you directions on what to code.
It lets you describe your program without prejudice, but writing it after coding makes you want to defend your code.
Writing comments before coding impels you to write codes in line with the comments. It also allows you to think before writing.
A lot of times, when you write without thinking, you will end up with terrible codes and use your comments to defend your shortcomings.
Benefits of writing comments
A bad comment is as good as a bad code, but a good one is priceless. In most companies, developers are mandated to write comments. The benefits of writing comments are numerous, but here are the important ones.
Comments clarify your goals
Sometimes you may be overwhelmed by the task at hand that you would be confused about where to start. You may be unsure of the algorithm to use.
Through comments, you can break down the task into smaller chunks and from there, things will start getting clearer.
A reminder of what a code does
You can use comments to remind yourself what the code is trying to do. There are many approaches to solving a problem. Through comments, you can state the reasons for choosing a particular approach.
Also, it can serve as a reminder of the functionalities to be included program. This way, you can track progress.
Makes it easy for other programmers to work with your programs
Your teammates or whoever comes across the program will find it easy to follow along. Comments help the writer and others to make sense of codes.
Good comments make it easy for programs to be maintained. If you don’t do it this way, in future, you find it difficult to understand your codes, especially in a large project.
Conclusion
While you strive to write good programs, ensure that you take the time to write good comments. Do not write comments for the sake of writing comments.
Learning how to write will not only make your programs easy to maintain, it makes your code clean. Grab a copy of Clean Code: A Handbook of Agile Software Craftsmanship and learn how to write elegant, clean and easy maintenance codes.