21–30 of 100 posts
+1 exactly this. Aside from "why", or explaining overly clever one-liners, the kind of comments I always find necessary are those providing before/after example of data during a transformation; and example strings w/ resulting capture groups for regular expressions. Example: # "tag1,tag2,tag3:val" => tags: [tag1, tag2], metadata: [tag3:val] # fun one-liner goes here
Earlier quoted context omitted.
>Comments are no exception. but they usually are.
Well this seems like a problem with code reviews (or lack of), rather than with the comments themselves.
The biggest problem I have with comments is that they quickly fall out of sync with the code. The code gets updated but the comments stay the same. Now you have a situation worse than no comments: misleading comments. It sometimes happens with self-documenting code too, but only when someone refactors enough of the code so that the class or method no longer matches the original name.
The danger of stale comments is, I feel, overblown. First, other developers know that comments can grow stale, so they're unlikely to treat them as sacrosanct, although I admit to falling into that trap. More importantly, most of the types of comments that Eric recommends can drift out of sync with the code and still be useful. Why is this code here? What happened previously that is no longer in the code? What tradeo…
Yes, because they should be, and are, largely ignored. Of course, deleting them is better than ignoring and not having them in the first place is better than deleting.
I think the Uncle Bob quote is good: "Code comments are not the Schindler's List. They're not pure good." If a line of code has a comment attached to it, the reader needs to understand both the code and the comment. The comment is written in natural language. There are multiple ways of understanding it. It must be written with great care so that people reading it don't misunderstand it. Otherwise it will likely just…
Earlier quoted context omitted.
Well this seems like a problem with code reviews (or lack of), rather than with the comments themselves.
It's a matter of incentives. Business folks don't care about comments unless they have a dev background. Your options are then to focus on the incentives present in the situation, or materially harm your own life and well-being by working extra hours to make up for your management's inability to manage.
Just because business folks don't know how to value certain developer practices doesn't let you off the hook. Just do what you have to do and if it takes longer because you had to learn how to do it, then it takes longer.
Let the business folks tell you when it's taking too long to deliver features.
The biggest problem I have with comments is that they quickly fall out of sync with the code. The code gets updated but the comments stay the same. Now you have a situation worse than no comments: misleading comments. It sometimes happens with self-documenting code too, but only when someone refactors enough of the code so that the class or method no longer matches the original name.
I hear this all the time as to why comments are "bad" (and I'm not suggesting that's what _you_ are saying, btw). Comments need to be kept up-to-date with code changes. The same way unit tests are kept up-to-date, and everything else around your code is. Comments are no exception.
In terms of developer resources, the act of doing updating the comments is cheap, but the act of making sure it gets done (in a systematic way) is comparatively expensive.
> Explaining previous approaches that didn’t work; explaining trade offs in the current implementation; marking possible improvements (TODOs) in the code; anything else you’d like to communicate with someone reading or developing the code To me, those are the functions of commit messages , not code comments. Of course, a "proper" IDE (and I don't know of any) would give you the context of the commit messages "impingi…
I think the Uncle Bob quote is good: "Code comments are not the Schindler's List. They're not pure good." If a line of code has a comment attached to it, the reader needs to understand both the code and the comment. The comment is written in natural language. There are multiple ways of understanding it. It must be written with great care so that people reading it don't misunderstand it. Otherwise it will likely just…
I really don't get this attitude. Code cannot tell you what is not there, no matter how clearly you write it.
Also, code doesn't have to tell you _everything_. It doesn't have to tell you "what is not there".
Maybe we can both learn here if you elaborated what you think code cannot tell, yet it should?
To distill that down, document a lot but don't rely on comments you find to be correct.