I believe you confused the ‘how’ of commenting the ‘why’ with ‘why’ of commenting the ‘why’, if that makes sense.
I am already aware of and totally agree with the need to document your code in this fashion for the convenience of others and self. What I am troubled about is its implementation in real life. How does one write comment that explains the ‘why’ of the code? How would I know if I haven’t accidentally written something that explains the ‘what’ instead or anything that is simply redundant? It seems like this portion is left out ‘as an exercise for the reader’.
I think that, in many cases, “what” and “why” are very similar to each other or are closely related.
I’ve had an experience like this on more than one occasion - I come into an established code base for the first time. I’m working on a new feature/refactor/bug fix. I am reading through a function that is relevant to me, scratching my head a bit, and thinking “I think I see what this function is doing, but why did they do it such a screwy way?” Often there are no comments to give me any clues.
In the past, I have foolishly changed the code, thinking that I knew better… But what often happens is that I soon discover why my predecessor did something that looked so weird to me. They weren’t stupid - there was a reason for it! And then I end up putting it back…
Point being, in a situation like that the “what” and the “why” are going to have a lot of overlap. So, personally, I try to write comments that highlight assumptions that won’t be obvious from reading the code, external constraints that matter but don’t actually show up in the code, and so on.
I am far from perfect at it and I probably don’t write enough comments. But when I do, I try to write comments that will be reminders to myself, or fill in gaps in context for some hypothetical new person. I try to avoid comments that literally explain the code unless it’s particularly (and unavoidably) complex.
I believe you confused the ‘how’ of commenting the ‘why’ with ‘why’ of commenting the ‘why’, if that makes sense.
I am already aware of and totally agree with the need to document your code in this fashion for the convenience of others and self. What I am troubled about is its implementation in real life. How does one write comment that explains the ‘why’ of the code? How would I know if I haven’t accidentally written something that explains the ‘what’ instead or anything that is simply redundant? It seems like this portion is left out ‘as an exercise for the reader’.
I think that, in many cases, “what” and “why” are very similar to each other or are closely related.
I’ve had an experience like this on more than one occasion - I come into an established code base for the first time. I’m working on a new feature/refactor/bug fix. I am reading through a function that is relevant to me, scratching my head a bit, and thinking “I think I see what this function is doing, but why did they do it such a screwy way?” Often there are no comments to give me any clues.
In the past, I have foolishly changed the code, thinking that I knew better… But what often happens is that I soon discover why my predecessor did something that looked so weird to me. They weren’t stupid - there was a reason for it! And then I end up putting it back…
Point being, in a situation like that the “what” and the “why” are going to have a lot of overlap. So, personally, I try to write comments that highlight assumptions that won’t be obvious from reading the code, external constraints that matter but don’t actually show up in the code, and so on.
I am far from perfect at it and I probably don’t write enough comments. But when I do, I try to write comments that will be reminders to myself, or fill in gaps in context for some hypothetical new person. I try to avoid comments that literally explain the code unless it’s particularly (and unavoidably) complex.