概要
APIのパラメータとして期間の範囲を表す命名について、職場でいい議論がなされたので自分なりにまとめておく。
期間の範囲というのは「開始日時」「終了日時」のようなものを想定。
start-end
扱いやすそうなのはこれ。
日時の場合は、終了側が排他的であった方が扱いやすいことが多い。
※一ヶ月分取得しようと考えた際に、末日が月によって変わってしまうので、1/1-2/1
と検索可能なほうがうれしい
endは排他の命名としてリーダブルコードでも紹介されている。
ただしリーダブルコードでは begin-end
で紹介している。
startとbeginは基本的には置き換え可能らしいが、 startの対義はstopであるのが正しいようだ。
しかし開始時間は start time
のように表現することが多いので悩ましいところ。
Kotlinの TimeRanges が使っている。
startInclusive-endExclusive
開始が包含で、終了が排他であることが一目瞭然。
分かりやすさが重視されており、なかなかよい。
endは排他なのは前述の通りなのだが、英語が母語でない人に配慮したのかなと想像している。
しかし「長い/冗長」という意見もあった。(Docにちょっと書いておくくらいでいいのかも、という声も)
Javaで時間の範囲を扱うクラスの引数は上記のような命名になっている。
since-until
ほぼ間違いなく時間を指すだろうことを連想できる。
unitlも排他になる。
しかしsinceはどうやら未来のことを表現するのに相性がよくないようなので、性質をよく考慮したほうがいいかもしれない。
(since には「ご存知のように」的なニュアンスが含まれるらしい)
Goの time.Duration や、 RailsのActiveSupportの Duration はsince-untilのようだ。
from-to
from-toの場合は、時間軸には向いていないかもしれない。
from Sender to Reciever のように、時間以外の表現の場合は有力な選択肢になりうる。
ちなみにGoogleカレンダーの予定の入力欄を英語版で見たところ from-until
でした。
offset-limit
limitは包含のニュアンスになるので、日時を扱う場合は微妙になる。
ただSQL等で使われる馴染みのキーワードであるので、包含させたい場合は有用。
first-last
こちらもlastは包含される。
min-max
maxは包含される。
あまり時間には使わなそう。
Rubyの Time は Comparable のbetweenを使ってるっぽいので、 min-maxってことになるのかな。