Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

The 'at' naming convention #508

Open
TimLovellSmith opened this issue Nov 16, 2023 · 0 comments
Open

The 'at' naming convention #508

TimLovellSmith opened this issue Nov 16, 2023 · 0 comments

Comments

@TimLovellSmith
Copy link
Member

TimLovellSmith commented Nov 16, 2023

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.

@TimLovellSmith TimLovellSmith changed the title The happened 'at' naming convention The 'at' naming convention Nov 16, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant