5 ways to write better comments

Another essential skill every programmer needs to master is writing good comments. Of course, you can write fewer comments in the tech community if you master the art of writing readable code. Still, we can never stop writing comments altogether. So, even if you’re good at writing code, you still need to be able to write good comments.

Comments are an essential part of any good code. Suppose you open a code that doesn’t have any comments; reading and understanding that code will be challenging and time-consuming. The lack of comments is equally as bad as using an overwhelming amount of comments. If your code files contain 50% or more comments, then your code is probably not very well-written, hence why you needed a lot of comments to explain it.

Luckily, writing good comments is not difficult; it just requires a lot of practice. So, how do you write good comments? In this article, we will go over 5 tips to help you write better, clearer comments.

Tip 1: Keep it short

When it comes to writing comments, less is more. Try not to over-explain every step of the code. Keep your comments short, within three sentences for classes and functions and one sentence of in-line comments. You will only need to give the users (fellow programmers) a hint of why you made some decisions and the overall functionality of the different sections of code.

As a general rule, when writing comments (docstring) for a class, include a brief description and date of the last modification. However, when you write one for a function, it must contain a description of its purpose, parameters and results.

Tip 2: Maintain a uniform style

Codes are divided into functions, classes, modules, libraries, etc. Each of these can be thought of as a level of the code. Therefore, when you write comments, it is better to develop a specific style for each level and maintain it throughout your code.

So, you will use the same style of writing docstring for all your code classes; the same goes for your functions and in-line comments. That will help anyone reading the code go through it quickly and understand its structure without going in-depth.

Tip 3: Write code and comments at the same time

One of the biggest mistakes people often make when they first learn to code is writing code and then going over it to write comments. The problem with this approach is that often, it takes us a while to develop our code; it could take days or even months. So, by the time we approach the comments writing step, we have forgotten why some decisions were made.

Some programmers say you should write the comments before writing the code, but, in my opinion, moving your code and comments in parallel is the most time and effort-efficient approach.

Tip 4: Be clear

Comments are not just for people who will read your code in the future; they are also for future-you who will maintain and expand on it during the next development steps. So, making your comments clear will help other developers and yourself.

Tip 5: Keep it simple

Keep your code simple, so it doesn’t need a lot of explanation in the comments, while keeping your comments simple as well.

One of the basic programming principles is to Let your code speak for itself. Although that movement was initially started by programmers who do not like to write comments generally most of the time, you can’t eliminate comments 100%. Still, you can significantly decrease the number of comments by practising writing a simpler code.

Being a good programmer means writing clear, readable code and concise, explicit comments. Both are equally important to producing high-quality code. However, most people focus more on developing their code writing skills and overlook working on their comments-writing skills.

Like any other skill, the only way to get better at writing comments is to practice writing better comments. When you come across comments that you think are well-written, reflect on why you liked them and how you can adopt a similar approach to writing your own comments. Often, short, clear, descriptive and not overused comments are the most optimal.