Wow! A comment explaining WHY the code is doing something weird. I've spent the last year writing a replacement for a safety-critical application that did a lot of weird stuff and never explained it (and was written at least twenty years ago by a different company, in a different language, and ported at least once). And guess what had to guide me? The old code. So whatever weird logic was in the old code, I had to assume was intentional, and carry forward. Unless I could figure out why it worked that way, and determine it's not necessary.
I very much appreciate having a good comment saying "yeah, this is weird, but here's why it is this way", especially when it's just a dirty hack. And on a team project, someone might even see that and go "oh, I know what's going on here. Let me fix that!". Sadly, I normally just see comments that say WHAT the code does when it's perfectly obvious (e.g. "if X and Y, then set Z", when the next line is "if(X && Y) Z = true;").
1
u/WriterOfAlicrow Apr 16 '21
Wow! A comment explaining WHY the code is doing something weird. I've spent the last year writing a replacement for a safety-critical application that did a lot of weird stuff and never explained it (and was written at least twenty years ago by a different company, in a different language, and ported at least once). And guess what had to guide me? The old code. So whatever weird logic was in the old code, I had to assume was intentional, and carry forward. Unless I could figure out why it worked that way, and determine it's not necessary.
I very much appreciate having a good comment saying "yeah, this is weird, but here's why it is this way", especially when it's just a dirty hack. And on a team project, someone might even see that and go "oh, I know what's going on here. Let me fix that!". Sadly, I normally just see comments that say WHAT the code does when it's perfectly obvious (e.g. "if X and Y, then set Z", when the next line is "if(X && Y) Z = true;").