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