Any excellent engineer should be able to write high-quality code comments. It will help boost your projects’ quality as well as your coding speed. So, how to become better at code commenting?
There are numerous resources for writing code comments. Yet, beginners may need more basic tips. If you are new to this practice, don’t skip the guide below.
I will introduce the basis of writing code comments in this post. I will also list some helpful tips to help you practice it more effectively.
Let’s find out the guide to code commenting right now!
What Is Code Commenting?
Code commenting is writing short and single-line notes in your codes. Each note in this practice is a comment. It helps explain how the program will work as well as its purpose.
Comments don’t affect your program directly. Yet, they are an indispensable part of the code readers. Most coders will use comments to explain their codes. For example, you use a comment to explain the purpose of a specific function.
It helps readers sort out the things that are too complex in the codes. Thus, you can clarify your purpose behind a block of code.
Types of Comments
There are two primary types of comments in coding. The sections below will tell you more about their features and purposes.
Contextual Comments
This type’s primary use is to describe the purpose or the features of a code. These things are typically not obvious when readers look at your projects. The most popular variety of contextual comments is logic comments.
They explain a specific block of code in a context. When you use these comments properly, they will help save tremendous time in checking codes. Plus, they help the readers avoid misunderstanding a code’s context or purpose.
Thus, coders usually use contextual comments when the codes are too complex. They never use them when a function’s purpose is already apparent to readers. Also, they are not applicable in APIs or libraries.
FIXMEs/TODOs
Also known as single-player tools, TODOs mostly decline the quality of your codes. Typically, coders use this type to dump thoughts temporarily. Thus, they can concentrate more on the current tasks.
Yet, TODOs can create an endless backlog that stays inactive when you push them. So, you should only use them to assist your personal coding process.
Guide To Code Commenting
Writing good code comments can boost your code’s quality. It also helps readers understand your sections quickly and avoid confusion. Here are some practices that will help you get better at this task.
1. Always Be Clear and Concise
The goal of comments is to help readers understand your codes. Thus, they should be as simple and intuitive as possible.
To achieve this, you can focus only on the critical points of your comments. Avoid using complex jargon to keep them concise.
2. Comment Intent
The comments are put in front of each file or function. They help explain the intent of that subject. Thus, they allow coders to explain the importance and purpose of the code.
3. Complex Algorithms
A comment is only necessary if you use a complex algorithm. It helps readers get the complex logic quickly. Also, they can make future adjustments to your codes more effectively.
4. Outputs and Inputs for Document Function
The position of comments for functions is a little different. You should comment on the input of data types in this case. It helps explain the output or side effects. Thus, the comments will decide if the functions are usable.
5. Clarify Complex Code Blocks
Assume you are a reader checking your own codes. Do you encounter any section that needs to be clarified? Comments are always necessary in these cases. They will explain the purpose of the code or any potential pitfalls.
6. Comment Declarations
Comments are also applicable for declarations. They clarify their usage and purpose. They are also essential for vague names with complex intent.
7. Document Modifications and Fixes
You need to leave comments when changing any code or fixing the bugs. The comments tell the reason why you modified your projects. Thus, the readers can address the problem and come up with practical implications.
8. Avoid Using Obsolete Comments
There are various types of comments. It’s critical that you review all of them and remove any obsolete comments. They can cause confusion and hinder the code development process.
9. Use Headers
Comment headers are effective in explaining large-sized code blocks or files. They give you a detailed overview of these sections. Readers can also understand more about details like the creation date and the code’s author.
10. Be Consistent
Lastly, develop a standard commenting format and style for your team. Then, stick to the decided form, so your comments and codebase can be consistent.
Also, you cannot use comments interchangeably with well-written codes. They are only supplemental elements for your codes. It would be best if you keep your codes clean and simple so they don’t need any comments.
How To Practice Code Comments Effectively?
Here are some extra tips that help you practice writing code comments. They will help increase your efficiency when developing the codes.
1. Focus On The Reason
I have only one priority when writing the comments. It is to keep my codes and comments as simple as possible. Thus, it would be best if you only used comments to explain complex functions.
2. Create Issues Rather Than Pushing To-dos
As mentioned above, TODOs serve best as single-player tools. Pushing them can result in an endless backlog that can be activated. Thus, it would help if you focused on creating issues.
3. Chose and Document Conventions
Documenting the conventions will increase the consistency of your comments. For example, you must decide the formats and when they would be used in a programming language.
This process can be flexible depending on your projects and purposes. The ultimate goal is to make your comments understandable and consistent.
4. Rounding Up
The purpose of code comments is to:
- Boost your morale
- Manage the tech debt
- Improve your work quality
- Enhance the engineering speed
Final Thoughts
Excellent code commenting is not all about your code’s quality. It’s the ability to know when to use and avoid using them. This process requires constant practice to accumulate more experience.
When writing comments, it would be best if you stay concise. Also, only use this tool if you find them necessary in the situation. Thank you for reading this post!