4 ms·
I think the argument is about comments like this // function to get the recipes function getRecipes() { ... } which are redundant and pollute the code
by ggregoire 5y ago
I think the argument is about comments like this
// function to get the recipes
function getRecipes() { ... }
which are redundant and pollute the codebase.
Where have you heard that writing useful comments (e.g. explaining an edge case, explaining a technical workaround, etc) is a bad practice?
- doliveira 5y agoI find it inconsistent to have it for some public methods and not for others. I guess you could add a (!) depending on the context: // function to get the recipes (!) function getRecipes() Or just document what recipes actually mean within the application context.
- Gigachad 5y agoI have found that I almost always benefit from a comment for each database table / model. The name can be somewhat descriptive but often its generic enough that its hard to tell if it specifically works the way I assume it does.
- layer8 5y agoThere is a minority of developers who believe that code can and should be mostly self-documenting, and that comments should be avoided because they become outdated and nobody reads them anyway. For example: http://web.archive.org/web/20100415205750/http://blog.weaponizedgames.com/every-comment-is-an-admission-of-failure http://web.archive.org/web/20100415205750/http://blog.weapon...
- fallat 5y ago> Where have you heard that writing useful comments (e.g. explaining an edge case, explaining a technical workaround, etc) is a bad practice? They are pretty clear about "useful comments" - by what they wrote, it sounds like they already understand what you wrote.
- ggregoire 5y agoI 100% agree that code should be self-documenting. I sometimes create intermediary variables or extract 1-2 lines of code into functions just so that the code can be understood just by reading the names of the variables and functions. But there is also information that you can't just describe into the code. There are the examples I already gave above. Another one could be what I did this afternoon: I had 2 options to solve a problem, I chose the more complicated one but the one that works in every case. I added a 4 lines comment describing the second option and why I didn't use it. There is no other way to add this information that would be useful for me or another developer in the future other than a comment.
- Agentlien 5y agoI've had to do exactly this. I sometimes write some code then realise that anyone less familiar with the details would look at it and see an "obvious improvement" which introduces a subtle bug. At least once I forgot to add a comment in such a case and luckily I got the question of "why not just..." in the code review.
- Izkata 5y agoNote that their bad example is comment-every-line style just like GP's example. No-comment self-documenting code is largely a backlash to this style, which is how introductory coding courses teach (taught?) was the right way to do comments. For a lot of programmers who first started in in one of these courses it tended to stick because they were never taught another way.
- t0suj4 5y agoMy algorithm for commenting is simple: If I don't understand what a line of code does, I delete it. If the behavior stays the same then it shouldn't have been there in the first place. If removing the line breaks something I put it back and add a comment explaining why it belongs there.
- alanbernstein 5y agoThat seems... Dangerous
- ensiferum 5y agoYeah this is impossible because code that isn't written cannot document itself and then the only option is to have a comment. And sometimes the meaningful thing is exactly what doesn't exist. For example here we're not doing X because of Y.
- layer8 5y agoTo clarify: I’m not one of those developers, just wanted to note that they are out there and surface regularly, since the OP was asking.