I agree with the "comment why, not how" a lot. I'm actually a big fan of comments and push for developers to leave more, but I focus on the spots where the code can't be simplified anymore and it's still hard to read. Or the reason behind why we are doing it isn't clear.
It's easy to forget the business or technical reason why we had to do something and then not be able to find the ticket a year later explaining it.
Especially with the cadence that language and frameworks are updated today. The more efficient techniques may not have been available when the code was written. I personally have left a whole bunch of notes at the top of a Vue project explaining why I didn't use separate component files and modules (inexperienced dev team, no source code control implementation on site, no experience of setting up build pipelines etc.)
That's a good advice, I've heard the same principle in the short form "Comment why, not how."
I agree with the "comment why, not how" a lot. I'm actually a big fan of comments and push for developers to leave more, but I focus on the spots where the code can't be simplified anymore and it's still hard to read. Or the reason behind why we are doing it isn't clear.
It's easy to forget the business or technical reason why we had to do something and then not be able to find the ticket a year later explaining it.
Especially with the cadence that language and frameworks are updated today. The more efficient techniques may not have been available when the code was written. I personally have left a whole bunch of notes at the top of a Vue project explaining why I didn't use separate component files and modules (inexperienced dev team, no source code control implementation on site, no experience of setting up build pipelines etc.)
Yeah, I couldn't agree more 😅