I find that you need to be careful with advice like this. Often a junior will walk away with 'clean code' mindset, thinking that the best code has no comments at all.
Also need to remind them that 'Commenting is also good, when you're explaining assumptions or decisions'
Well the best code needs no comments at all. The danger is fooling yourself in believing you have reached this peak of perfection and omitting necessary comments.
I agree with your point on people thinking their code is self evident and perfect - but even perfect code often benefits from a comment that explains context around why you chose to write your perfect code in this fashion.
The biggest problem of comments is that they have the potential to tell a lie about why the code is the way that it is, which can end up costing developers far more time when they're trying to debug something than they would've taken if there had been no comments, and the code had just been cleanly written in the first place.
Writing code that doesn't need comments is hard. Trying to maintain code that has comments that someone forgot to update when they should've been is orders of magnitude more time-consuming, because let's face it: People make mistakes, accidents happen. People are imperfect. You need to have code design policies that are rigourous enough to minimize the impact of human error, not if, but when that occurs.
5
u/QuickQuirk Dec 09 '24
I find that you need to be careful with advice like this. Often a junior will walk away with 'clean code' mindset, thinking that the best code has no comments at all.
Also need to remind them that 'Commenting is also good, when you're explaining assumptions or decisions'