microsoft / microsoft/api-guidelines

The 'at' naming convention

Open
#508 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
No language data
Stars
23.3k
Forks
2.7k
PR merge metrics
No merged PRs in 30d

Description

I recently had to try to give feedback on API design, but...
I found myself emotionally reacting to the inflexibility of a particular guidance I was giving about the naming of date/time fields, in a self-doubting way.

Quotes:

I think azure naming conventions imply it should be called 'restartAt', not 'restartDate'
https:/github.com/microsoft/api-guidelines/blob/vNext/azure/ConsiderationsForServiceDesign.md#recommended-naming-conventions
Maybe since it is meant to imply a deadline in the future it should be restartBy though??
[I know, why don't we have both! "restartByAt" j/k ]

Similarly, there was a design with "estimatedShippingDateTime".
It could be "estimatedShippingAt", or "estimatedDeliveryAt".
But, after a certain point, you KNOW its after when it should have shipped. At which point, "shipping at" is, confusingly, the future tense, even though the estimate refers to the past. Compare to ("We estimated that it should have shipped at").

Also, in the context of delivery, "at" could mean a place as well as a time....

On the other hand "By" seems like it could solve some of these semantic and grammatical problems, for these cases where we're talking about not when something definitely happened, but when something was predicted, or requested to happen.

"restartBy"
"estimatedShipBy" (to avoid shipped vs shipping)
"estimatedDeliveryBy"

Revising the set of alternatives following the guidance, I suppose then it would be...

"restartAt"
"estimatedShipAt"
"estimatedDeliveryAt"

Are these really the best option? Also, is 'by' too much of a promise, in some sense? And is any of the guidance I'm giving by parroting this guideline really worth the space and time it takes up?

Reanalyzing what am I reacting to...
I don't have a problem with using 'CreatedAt' to talk about stuff that definitely happened in the past. Or is being scheduled to happen at a specific time in the future... 'CreateAt'....

But I have a problem with using it when its really talking about a range of possibilities... and that is really what 'by' (or 'after', or 'before', or 'until') is meant to express.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the issue and the linked ConsiderationsForServiceDesign.md section on recommended naming conventions. Compare the restart and estimated shipping examples, then look for a maintainer decision on whether the guidance should change. Done would require an agreed naming rule and a clearly scoped documentation update, but the issue does not identify a file or settled direction.

Written by the indexing model from the issue text.

Assessment

Domain
api, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.