5 Tips to Write Better Comment In Your Code | by Sara A. Metwalli | Jun, 2022
Help others to follow your code easier
As programmers or a part of the tech field, we often need to read, analyze, and write code regularly. Some codes are easier to write and follow than others. The clearer the code, the faster it will be to understand, use and build on. The ability to write good code is an essential skill for any programmer or data scientist.
But, one of the other important skills is writing good comments. Now, I know that if you master the art of writing readable code, you can then write fewer comments, but we can never stop writing comments altogether to be realistic. So, even if you’re good at writing code, you also need to be able to write good comments.
Comments are the main part of every good code. If you open a code and it doesn’t have any comments whatsoever, reading and understanding that code will be time-consuming. A lack of comments is equally as bad as using an overwhelming amount of comments. If your code files are 50% or more comments, then your code is probably not very well-written, hence why you needed a lot of comments to explain it.
Writing good comments is not a difficult task; it’s just one that requires a lot of practice. Luckily, if you’re reading this article, you’re either a programmer, a data scientist, or work in the tech field. This means you need to write/ read a lot of code in your career.
So, how to write good comments? In this article, I will go over 5 tips to help you write better comments and take your comments writing skills to the next level.
When it comes to writing comments, I would say, less is more. Try not to over-explain every step of the code. Keep your comments short, within 3 sentences for classes and functions and one sentence of in-line comments. If your code is well-written, you won’t need many comments to explain it. You will only need to give the users (fellow programmers) a hint of why you made certain decisions and the overall functionality of the different sections of code.
As a general rule, to keep things organized and the uniform amount the programming community, 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.
Often, codes are divided into chucks, 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 within your code.
So, you will use the same style of writing docstring for all your code functions; the same goes for your functions and your in-line comments. That will help anyone reading the code go through it quickly and understand its structure without even needing to read it in-depth.
One of the biggest mistakes beginners make when they first learn to code— which I did, too — is first to write that code and then go over the code and write comments. The problem with this approach is that often, it takes us a while to write code, days or even months. So, by the time we approach the comments writing step, we’d have forgotten why we made some decisions.
In this case, the best thing to do is to write comments as you write the code. Some programmers may even say that you should write the comments before your write the code (it will act as a guide for you). But, in my opinion, moving your code and comments in parallel is the most time and effort-efficient approach. So write comments as you go, and at the end, edit them if needed.
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.
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.” — Phil Haack
Finally, and perhaps the most straightforward tip, is to keep things simple. Keep your code simple, so it doesn’t need a lot of explanation in the comments while keeping your comments simple and to the point so others and future you find them easy to follow.
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 them, you can’t 100% eliminate comments. Still, you can decrease the amount of them significantly but writing a simpler code.
Becoming a successful data scientist requires you to master different skills; programming is probably on the top of the list of those skills. Being a good programmer means you can write clear, readable code and concise, clear 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. First, read comments that you think are well-written and reflect on why you liked them. Often, short, clear, descriptive, and not overused comments are the most optimal.
This article went over 5 tips that will take your comment-writing skills to the next level. I leave you with this; comments are not meant to explain the code to the users; instead, your code is used to explain the comments to the computer.
Help others to follow your code easier
As programmers or a part of the tech field, we often need to read, analyze, and write code regularly. Some codes are easier to write and follow than others. The clearer the code, the faster it will be to understand, use and build on. The ability to write good code is an essential skill for any programmer or data scientist.
But, one of the other important skills is writing good comments. Now, I know that if you master the art of writing readable code, you can then write fewer comments, but we can never stop writing comments altogether to be realistic. So, even if you’re good at writing code, you also need to be able to write good comments.
Comments are the main part of every good code. If you open a code and it doesn’t have any comments whatsoever, reading and understanding that code will be time-consuming. A lack of comments is equally as bad as using an overwhelming amount of comments. If your code files are 50% or more comments, then your code is probably not very well-written, hence why you needed a lot of comments to explain it.
Writing good comments is not a difficult task; it’s just one that requires a lot of practice. Luckily, if you’re reading this article, you’re either a programmer, a data scientist, or work in the tech field. This means you need to write/ read a lot of code in your career.
So, how to write good comments? In this article, I will go over 5 tips to help you write better comments and take your comments writing skills to the next level.
When it comes to writing comments, I would say, less is more. Try not to over-explain every step of the code. Keep your comments short, within 3 sentences for classes and functions and one sentence of in-line comments. If your code is well-written, you won’t need many comments to explain it. You will only need to give the users (fellow programmers) a hint of why you made certain decisions and the overall functionality of the different sections of code.
As a general rule, to keep things organized and the uniform amount the programming community, 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.
Often, codes are divided into chucks, 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 within your code.
So, you will use the same style of writing docstring for all your code functions; the same goes for your functions and your in-line comments. That will help anyone reading the code go through it quickly and understand its structure without even needing to read it in-depth.
One of the biggest mistakes beginners make when they first learn to code— which I did, too — is first to write that code and then go over the code and write comments. The problem with this approach is that often, it takes us a while to write code, days or even months. So, by the time we approach the comments writing step, we’d have forgotten why we made some decisions.
In this case, the best thing to do is to write comments as you write the code. Some programmers may even say that you should write the comments before your write the code (it will act as a guide for you). But, in my opinion, moving your code and comments in parallel is the most time and effort-efficient approach. So write comments as you go, and at the end, edit them if needed.
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.
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.” — Phil Haack
Finally, and perhaps the most straightforward tip, is to keep things simple. Keep your code simple, so it doesn’t need a lot of explanation in the comments while keeping your comments simple and to the point so others and future you find them easy to follow.
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 them, you can’t 100% eliminate comments. Still, you can decrease the amount of them significantly but writing a simpler code.
Becoming a successful data scientist requires you to master different skills; programming is probably on the top of the list of those skills. Being a good programmer means you can write clear, readable code and concise, clear 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. First, read comments that you think are well-written and reflect on why you liked them. Often, short, clear, descriptive, and not overused comments are the most optimal.
This article went over 5 tips that will take your comment-writing skills to the next level. I leave you with this; comments are not meant to explain the code to the users; instead, your code is used to explain the comments to the computer.
Denial of responsibility! Techno Blender is an automatic aggregator of the all world’s media. In each content, the hyperlink to the primary source is specified. All trademarks belong to their rightful owners, all materials to their authors. If you are the owner of the content and do not want us to publish your materials, please contact us by email – [email protected]. The content will be deleted within 24 hours.