4 ms·

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

by cjfd 3y ago

Smaug123 3y ago
In a language without units of measure, `get_height` should be documented!
- aidos 3y ago
  get_height_in_inches
  - Smaug123 3y ago
    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.
  - cycomanic 3y ago
    get_acceleration_in_m_per_s_squared?
- biofox 3y ago
  Lockheed Martin didn't get the memo: https://en.wikipedia.org/wiki/Mars_Climate_Orbiter https://en.wikipedia.org/wiki/Mars_Climate_Orbiter
- eschneider 3y ago
  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.
  - Smaug123 3y ago
    Specifically 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 ago
  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.
mlok 3y ago
get_height_in_cm ?
ReleaseCandidat 3y ago
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").
- JTyQZSnP3cQGa8B 3y ago
  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.
baby 3y ago
I’d gladly enforce documentation on every piece of code, even if that means some dumb documentation in some places

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

by cjfd 3y ago

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

Smaug123 3y ago

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

aidos 3y ago
get_height_in_inches
- Smaug123 3y ago
  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.
- cycomanic 3y ago
  get_acceleration_in_m_per_s_squared?
biofox 3y ago
Lockheed Martin didn't get the memo: https://en.wikipedia.org/wiki/Mars_Climate_Orbiter https://en.wikipedia.org/wiki/Mars_Climate_Orbiter
eschneider 3y ago
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.
- Smaug123 3y ago
  Specifically 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 ago
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.

mlok 3y ago

get_height_in_cm ?

ReleaseCandidat 3y ago

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

JTyQZSnP3cQGa8B 3y ago
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.

baby 3y ago

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