Well-Commented If Statements Make Software Robust

Many years ago I asked a question on stack exchange about self documenting code.

https://softwareengineering.stackexchange.com/questions/5130...

I spent many years trying to write my code well enough to not need comments. At the same time I just hit 9 years at my current job and what I’ve come to realise is although the code reads, and makes sense, it sometimes lacks context of why.

So for the last few years I’ve been trying to add brief supporting comments to explain /why/ something was done, or how it ends up in a certain state, etc.

As a result when I go back to that code week or months later I find adding functionality or fixing bugs much easier.

I try not to comment too much or too long unless I really need to.

Hello, author here! I agree with your sentiment. I was referring more to wonky edge cases in the post such as "if you're rendering a webpage on Windows with a scrollable div, add 10px to the right padding because the scrollbar is wider in Windows than macOS", not "if age < 21, user cannot buy alcohol". You should try to avoid stating the obvious in comments (obviously). I was trying to convey that sometimes it's OK to include information in comments that might rot, if it helps you remember why you did it in the first place. I've found that most of these edge cases are "set it and forget it", so it's more likely that your memory would rot before the comment did.

I'm in the same boat when it comes to knowing when to leave a comment. I might suck at it, but I subscribe to the belief that it's better to look like an idiot than an a$$hole. I might look dumb by stating the obvious in a comment, but it beats being someone who didn't bother explaining themselves because "good code is self-documenting" [eye roll].

I take obvoius comments any day over no comments. I read comments way faster than code. It is also good to have an overview of what stuff does when you try to read it.

The hostility versus unnessecary comments is just making devs cargo cult for "clean code".

It happens to me quite a bit. I come back to some code I wrote a couple of years ago. At the time the logic was "obvious". Now, I need to puzzle it out all over again. So I retrofit a suitable comment so that next time I won't be doing the same blank stare.

For me, most of what passes for programming is "refactoring" and fixing edge-cases.

@codelikeawolf rel=canonical link should only be used if your content is accessible on multiple URLs, and you want to point crawlers to a specific URL.

Thank you. I didn't really understand the argument of the article until I saw a production usage. I thought he was arguing that arrow code is okay if you add comments, but he's really saying that sometimes a single code path can't handle all the complexity of the world and special cases are OK.

I think this was what I referring to. Thank you!

Is there a missing dot in line 189? Otherwise domains like zhulu.com would match, wouldn’t it?

As someone from outside the field, this is crazy to me. Why does something as general as WebKit have host specific code?