Think back to the last time you looked at an unfamiliar block of code. Did you immediately understand what it was doing? If not, you’re not alone – many software developers, including myself, find it challenging to grasp unfamiliar code quickly…
Worse, refactors make comments wrong. And there is nothing more annoying then having the comment conflict with the code. Which is right? Is it a bug or did someone just forget to update the comments… The latter is far more common.
Comments that just repeat the code mean you now have two places to update and keep in sync - a pointless waste of time and confusion.
Yes- exactly, they make comments wrong. But comments aren’t always a waste of time, like in legacy code, or just in general code that isn’t gonna change (mathematical equations too)
Comments are not always a waste of time, but comments that repeat or tell you what the code is doing (rather than why) are a waste. For legacy code you generally don’t have comments anyway and the code is hard to read/understand.
But if you can understand the code enough to write a comment you can likely refactor the code to just make it more readable to start with.
For code that does not change generally does not need to be read much so does not need comments to describe what it is doing. And again, if you understand it enough to write a comment to explain what it is doing you can refactor it to be readable to begin with. Even for mathematical equations I would either expect the reader to be able to read them or link to documentation that describes what it is in much more detail to name the function enough that the reader can look it up to understand the principals behind it.
You make some great points. Using smaller functions and breaking up your code in readable bits makes a huge difference and you will likely never need comments if you do it right 👍🏻
Creating functions is IMO not the first thing you should do. Giving variables better names or naming temporaries/intermediate steps is often all you really need to do to make things clearer. Creating smaller functions tends to be my last resort and I would avoid it when I can as splitting the code up can make things harder to understand as you have to jump around more often.
Worse, refactors make comments wrong. And there is nothing more annoying then having the comment conflict with the code. Which is right? Is it a bug or did someone just forget to update the comments… The latter is far more common.
Comments that just repeat the code mean you now have two places to update and keep in sync - a pointless waste of time and confusion.
Yes- exactly, they make comments wrong. But comments aren’t always a waste of time, like in legacy code, or just in general code that isn’t gonna change (mathematical equations too)
Comments are not always a waste of time, but comments that repeat or tell you what the code is doing (rather than why) are a waste. For legacy code you generally don’t have comments anyway and the code is hard to read/understand.
But if you can understand the code enough to write a comment you can likely refactor the code to just make it more readable to start with.
For code that does not change generally does not need to be read much so does not need comments to describe what it is doing. And again, if you understand it enough to write a comment to explain what it is doing you can refactor it to be readable to begin with. Even for mathematical equations I would either expect the reader to be able to read them or link to documentation that describes what it is in much more detail to name the function enough that the reader can look it up to understand the principals behind it.
You make some great points. Using smaller functions and breaking up your code in readable bits makes a huge difference and you will likely never need comments if you do it right 👍🏻
Creating functions is IMO not the first thing you should do. Giving variables better names or naming temporaries/intermediate steps is often all you really need to do to make things clearer. Creating smaller functions tends to be my last resort and I would avoid it when I can as splitting the code up can make things harder to understand as you have to jump around more often.
I hear ya. As always, it’s a balance between having functions that are too long, and many too small functions. Matter of team preferences too.