"Do not comment on your code, it should be self-documented". Well... I don't agree.
Jean Santana
Posted on April 17, 2022
Since I started write my first block of code, I heard from many developers that commenting is useless and it's a type of apology to write a bad code, but after working in a big projects with a big team, the only thing I can say is: Not commenting your code is narcisist and excludes beginners, by the way, who said your code is so good and obvious as you think it is? Yeah, your mind.
During your work, probably you faced a function that you asked yourself: "-What the hell is even that?". Many of us experienced this situation, even with our own code after some weeks far from the project. Now, imagine if instead of you have to waste your time, searching through the houndreds of files for the right function you need to put hands on, you could have just comment your code telling the function purpose, its params and what it should return. Life could be a dream, right?
Also, we cannot asume the everybody think like us and we are being so obvious. People have different ways to analyze things, we have people that are less experienced or even have mental health conditions like, anxiety and ADDH, and that makes the process of understand some pieces of code even harder. Should we just exclude them because we can't use one single minute to comment our complexity? I think we shouldn't.
The question is not about if you should comment your code or not, but is what you need to comment in your code and how it should be done.
Write a clean and easily readable code is unegotiable, and you get better on this with experience, but you can also write clean and good comments, so it can be used as a reference for you and the others, and it do not make you a bad programmer, on the contrary!, It makes you a better professional,your code will be easily maintainable, plus, you're ensuring that no matter the level of who enters on your team, they'll get it faster and start working on the project, and if you have to leave your job, the devs that comes after you will be grateful and thanks you everyday before they going to bed. (okay, I'm not so sure about this last part).
“Programs must be written for people to read and only incidentally for machines to execute.” - Hal Abelson - MIT Professor.
Recommended reads:
Best practices for writing code comments
Posted on April 17, 2022
Join Our Newsletter. No Spam, Only the good stuff.
Sign up to receive the latest update from our blog.
Related
April 17, 2022