One of the controversial topics among developers is about writing code comments. I see a lot of developers no longer writing any kind of comments inside their codebase (with the exception of ‘TODO’ comments that can be found in almost every codebase).
Side note: If any comments are found in the codebase they are typically generated afterwards, and I think with the introduction of AI in the developers toolbox, this will not get any better. These type of comments don’t add a lot value as they just emphasize the obvious and repeat the information already found in the code.
When I ask developers why they don’t write any comments, the typically answer is
Code should be self-explaining.
And although I agree with the statement above not all information about the code could be expressed through the code alone.
Another excuse I hear a lot is that developers see it as a code smell because code that needs comments is probably badly written and could be refactored to something more readable and expressive.
Comments are not an excuse for sloppy code.
I think that writing comments is really important (and similar to start writing a test before the implementation when using TDD) I always start with writing comments. Doing this improves the system design as it forces me to think first and code later. To write a good comment, you must identify the essence of a variable or piece of code: what are the most important aspects of this thing? It’s important to do this early in the design process; otherwise you are just hacking code.
The act of writing comments allows you to evaluate your design decisions, so you can discover and fix problems early in the process.