Hacker News Reader

Comment by ahoka | Hacker News Reader

Useless blanket advice. Of course you should write meaningful comments.

Not 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.

OK:

   # remark on uselessness of blanket advice
   Useless blanket advice.

This 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

Or the useless comment is the only thing that doesn't make sense. Which is far more common in my experience.

Quite, 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.

Your problem is that you wrote a bad comment, not that you wrote a comment

This is not so very 'of course'. There is lots of documentation nazis out there forcing you to document that get_height 'gets the height'.

In a language without units of measure, `get_height` should be documented!

get_height_in_inches

My point is that it's extremely common for people to go "this doesn't need to be documented", and then I come along as a user of the library and have to actually run the thing to determine its semantics.

get_acceleration_in_m_per_s_squared?

For 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.

Specifically in languages with types and zero-cost abstractions. If it's not zero cost, then… there's a cost, which must be weighed.

Lockheed Martin didn't get the memo:

https://en.wikipedia.org/wiki/Mars_Climate_Orbiter

Indeed. 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.

get_height_in_cm ?

I 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").

In 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.

I’d gladly enforce documentation on every piece of code, even if that means some dumb documentation in some places

Reply on news.ycombinator.com