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.
You are not logged in. However you can subscribe from another Fediverse account, for example Lemmy or Mastodon. To do this, paste the following into the search field of your instance: !programmerhumor@lemmy.ml
Post funny things about programming here! (Or just rant about your favourite programming language.)
Rules:
Posts must be relevant to programming, programmers, or computer science.
No NSFW content.
Jokes must be in good taste. No hate speech, bigotry, etc.
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.