rails/rails — comment on commit 0306f82e0c3cda3aad1b45eb0c3a359c254b62cc
File: railties/lib/rails/generators/rails/app/templates/config/environments/development.rb.tt line 31
By yfeldblum:

I definitely agree with a preference for crystal clear names.

For local variables and private methods, the philosophy of achieving perfect clarity by including units in names is great. If your method requires zero extra brain cycles to read, because the locals it uses and the other private methods it calls include units in their names, perfect. That makes the implementation crystal clear. And that's definitely something we should all be doing.

But I think a different aesthetic applies to names in public APIs. For API names, it's the intention which must be crystal clear, not necessarily the implementation. It's easier to get an intention across with names that are shorter and sweeter than the names one might use in an implementation by omitting implementation-related details and leaving only intention-related details. The name *threshold* is clear about the fact that one can configure a threshold - the intention - than is the name *threshold in seconds*, which is far more clear regarding *how* to configure the threshold than it is in that what one is configuring *is* a threshold.

Here, to communicate an important detail about the API, it is better to put that detail in the documentation *and* in the comment directly about the auto-generated line in the default development config. The comment can explain the detail "either an integer or float in seconds, or an ActiveSupport::Duration instance," and can make that details crystal clear, without overloading the intention-oriented API name with it.