? semantic hinting

[geemus]

To better communicate the purpose/intention of attributes it can be useful to use semantic hints (similar in a sense to type hints). They generally appear as suffixes to attribute names, a couple examples we use consistently:

• #{past_tense_verb}_at for timestamps
• #{past_tense_verb}_on for dates (time can be ignored and/or should be midnight)

Another case we have discussed, but that I'm not quite as convinced about yet. I'm not sure how universal it is, but I think it does make it more human-readable and a bit easier to reason about:

• #{noun}_enabled for boolean values. Historically we have a mix of these and just #{noun} for boolean attributes, it seems as though choosing one or the other at least would be better.

[geemus]

/cc @garyposter @pedro - I know we discussed this a bit recently, so I'd certainly welcome your thoughts. Thanks!

[pedro]

Nice, this looks great to me!

I'm not sure about how universal the _enabled attributes should be either. Looking at our boolean attributes I kinda like the simplicity of maintenance and beta, as opposed to maintenance_enabled and beta_enabled.

I prefer it in particular for writeable attributes, where a change to a noun (eg: PATCH /apps/foo, maintenance: true) reads better than a change to a verb in the past tense. On the other hand it would be really nice to just have a consistent standard...

[geemus]

Hmm. It might point to a broader issue with naming. ie, maybe it should be maintenance_mode_enabled and beta_features_enabled or similar? Much more verbose, but I think they might also be clearer than just maintenance and beta. What do you think?

[pedro]

Hmm not sure the new terms add much. For instance, I don't see any ambiguity in "maintenance" to justify "maintenance mode".

"Beta features" is interesting because it does correlate with account/app features, but in practice this flag also gives users access to private beta addons, so this might call for the more generic name.

[geemus]

maintenance vs maintenance_enabled would be fine too and I think helps a bit. Probably not so much that it is worth us changing it, but maybe enough that it would be a good guideline for future work. Beta is definitely an outlier, so perhaps that isn't a good example at all...

[frankieroberto]

How about _count for integers representing counts of things (e.g. logins_count or followers_count on a User object)? Seems to be quite a common convention.

[geemus]

@frankieroberto - yeah, definitely another good case to include.

[garyposter]

I do like the idea of using suffixes as clear indicators of data types. OTOH it doesn't feel natural enough yet for bools, per Pedro's examples.

I'm not sure I entirely agree with @pedro that "maintenance" has no ambiguity. If I know it is a bool, it's fairly clear, but otherwise it could be a date with one semantic, or a comment field with another.

A #is_{adjective} might be another approach for bools? That has some precedent, I think, and is nice and short.

[frankieroberto]

I'm not particularly keen on is_{word} for booleans, mainly because it feels better to just pick words which self-describe as binary on/off choices (like active, deleted, suspended, etc).

It's also worth considering that most usage of boolean attributes will probably be checking whether maintenance evaluates to true rather strictly equals true, which has the benefit of allowing a boolean json attribute like maintenance: true to be changed to an object like:

maintenance: {started_at: '2014-01-01T02:41:30'}

...without breaking any API clients.

[jroes]

I'm a fan of type annotation for booleans via prefixes/suffixes. I've too often had to ask "is deleted a date or a boolean?" when filtering data in a foreign-to-me database.

[frankieroberto]

@jroes if all dates end in _at or or _on, that ambiguity disappears! ;-)

[geemus]

@garyposter is_ does have some precedent, but I guess I don't feel awesome about it in this context.

@jroes I agree that something seems likely to be valuable, just still not sure what.

@frankieroberto very true. That said, I think in terms of disambiguation, presence of something beats absence of the other thing. That said, it seems hard to nail down a discrete naming convention that works for all booleans (so far anyway). Even in your example I wish for greater consistency I guess, ie deleted and suspended are different from active (activated would be more consistent I think).

Maybe it is a matter of saying that booleans should just be past-tense verbs (or at least end in one). I would expect other attributes to be nouns (or end in at/on like times/dates), so this in and of itself colud potentially disambiguate. Examples from above would be activated, deleted, enabled. Then perhaps beta_allowed and maintenance_enabled. Looking at these now though, I wonder if it should be past tense verb first instead of last, ie allowed_beta and enabled_maintenance. I think verb-first reads a bit better maybe. Thoughts?

[JOEFOSTER9]

Don't understand any it

[geemus]

@JOEFOSTER9 any questions I could help with?

[JOEFOSTER9]

What exactly is this

[JOEFOSTER9]

How do u use this

[geemus]

The idea here is to name properties following a particular pattern in order to hopefully make it clearer to an end user what the type and intention of the property might be.

[JOEFOSTER9]

Examples?
On Mar 25, 2016 5:27 PM, "Wesley Beary" notifications@github.com wrote:

The idea here is to name properties following a particular pattern in
order to hopefully make it clearer to an end user what the type and
intention of the property might be.

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
#33 (comment)

[geemus]

The easiest examples are probably things like created and update timestamps. You could for instance have:

created_at and updated_at if these were timestamps (date + time)

or

created_on and updated_on if these were just dates

It's a small point really, but it seemed like it might be a nice guiding principle when naming some things. The trickier extension, mentioned above, is if there was a reasonable way to have a similar suffix to indicate something is a boolean. The proposed version was ..._enabled so, for instance a boolean about whether maintenance was flagged on or off might be maintenance_enabled instead of simply maintenance. The hope again being that it gave a bit clearer hint to the end user that it is a boolean and also, at least in this case, it might give a bit more context around how to use it.

[JOEFOSTER9]

Stop
On Mar 25, 2016 5:34 PM, "Joe Foster" joefoster1891@gmail.com wrote:

Examples?
On Mar 25, 2016 5:27 PM, "Wesley Beary" notifications@github.com wrote:

The idea here is to name properties following a particular pattern in
order to hopefully make it clearer to an end user what the type and
intention of the property might be.

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
#33 (comment)