3 ms·
Useless blanket advice. Of course you should write meaningful comments.
by ahoka 3y ago
Useless blanket advice. Of course you should write meaningful comments.
- cjfd 3y agoThis is not so very 'of course'. There is lots of documentation nazis out there forcing you to document that get_height 'gets the height'.
- Smaug123 3y agoIn a language without units of measure, `get_height` should be documented!
- aidos 3y agoget_height_in_inches
- biofox 3y agoLockheed Martin didn't get the memo: https://en.wikipedia.org/wiki/Mars_Climate_Orbiter https://en.wikipedia.org/wiki/Mars_Climate_Orbiter
- eschneider 3y agoFor languages with types, you can (and absolutely should) use types for your units (rather than raw double/float/int) and encode your conversions into your types. You can thank me later.
- Smaug123 3y agoSpecifically in languages with types and zero-cost abstractions. If it's not zero cost, then… there's a cost, which must be weighed.
- magicalhippo 3y agoIndeed. We've just been through this a few days ago here with a customer. We have fields for gross and net weight, GrossWeight and NetWeight, and the official systems which we talk to expect this to be in kg, so "of course" our fields would be in kg as well. Well, nobody documented units in the file exchange documentation, so customer sent us weights in grams because that's how they stored it.
- mlok 3y agoget_height_in_cm ?
- ReleaseCandidat 3y agoI get suspicious whenever I see some undocumented functions when others are documented. The question is if it has been deemed to trivial to document or if the original documentation had been wrong and removed (because for example `get_height` does not just return "the height").
- JTyQZSnP3cQGa8B 3y agoIn all the projects I worked on, the comment disappeared after a few years, or removed thanks to OPs method. And the code became unreadable. I have never seen code that was self-documented. It’s always a mess because the devs are too lazy to write comments.
- baby 3y agoI’d gladly enforce documentation on every piece of code, even if that means some dumb documentation in some places
- jjgreen 3y agoOK: # remark on uselessness of blanket advice Useless blanket advice.
- dvh 3y agoThis is EXACTLY why it should be there. Because in the real world, after 2 years and 3 programers and 2 managers later it will became: # remark on uselessness of blanket advice if (!translation_db_connected) { throw "Cannot connect to translation database"; } check_permissions(); if (Date.week() % 4 === 0 && !is_admin()) { echo_xf(i18n.monthly_maintenance_warning); } echo_bf(i18n.context_translate('remark458')); check_dangling_block(); if (WM_API >= 7) { nxptr_free(i18n.handle); } And suddenly the useless comment is the only thing that makes sense
- rcxdude 3y agoOr the useless comment is the only thing that doesn't make sense. Which is far more common in my experience.
- jjgreen 3y agoQuite, according to the Excel spreadsheet, "remark458" is "it takes many a mickle to make a muckle", that must be a typo for "remark485", oh, or could be the comment is in the wrong place. If only there were a single source of truth.
- baby 3y agoYour problem is that you wrote a bad comment, not that you wrote a comment
- makeitdouble 3y agoNot writing dumb/ephemeral comments is another thing altogether. In particular it's easy to require comments everywhere. It's a rule people don't have to think much about, and most linters will provide out of the box rules to flag methods and class variables without comments.