I agree and even for my own side projects, where I'm writing everything I often forget different parts.
We end up spending a lot of time naming things (variables, functions, classes etc) well, we forget we can also just include a longer description to help.
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.
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.
A good if statement will tell the reader why the case is there.
I often see comments from junior developers that more or less re-state what the code already says.
// Do the thing if foo
if (foo)
thing();
These types of comments are just noise because they add no additional info. Now, if the comment had told me why we do thing in case of foo, it would actually be helpful.
I’m not in favor of “space shuttle” commenting because it is too easy for comments to rot. Still, it’s hard to know when to leave a comment, and it’s a skill I’m continuously improving on.
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.
You beat me to the "self documenting code" thing by 10 minutes! I never bought in to the whole "clear code doesn't require comments" belief, mainly because the clearest function in the world can't provide details about its role as part of a larger system. Also, you sometimes just have to do weird stuff to get things to work (usually because they're out of your control). Rather than trying to retrace your steps every 6 months when you look at that code, a sentence or 2 describing its purpose gets you up to speed. I've been burned by zero comments way more times than I've been burned by incorrect comments.
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".
I’m kind of a stickler for comments like this. The more context and rationale that can be provided at a glance the faster future contributors can understand the current state.
@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.
17 comments
[ 6.2 ms ] story [ 66.4 ms ] threadWe end up spending a lot of time naming things (variables, functions, classes etc) well, we forget we can also just include a longer description to help.
For me, most of what passes for programming is "refactoring" and fixing edge-cases.
I often see comments from junior developers that more or less re-state what the code already says.
These types of comments are just noise because they add no additional info. Now, if the comment had told me why we do thing in case of foo, it would actually be helpful.I’m not in favor of “space shuttle” commenting because it is too easy for comments to rot. Still, it’s hard to know when to leave a comment, and it’s a skill I’m continuously improving on.
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.
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].
The hostility versus unnessecary comments is just making devs cargo cult for "clean code".