Hacker News Reader

Comment by cjfd | Hacker News Reader

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

View on HN

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.

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

get_height_in_cm ?

Reply on news.ycombinator.com