英語でエラーメッセージを書く時、英語ネイティブでない私は下記のような点に悩むことが以前はよくありました。
- 先頭の文字を大文字にすべきか否か
- 文章で書くべきか、短いフレーズにすべきか
- （文章の場合）ピリオドを付けるべきか否か
- 冠詞を付けるべきか否か
- 形容詞を前置にすべきか後置にすべきか（例：'Not found user' それとも 'User not found'）
- エラーメッセージは文章でよいとして、エラークラス名はどうすべきか
- エラークラス名にbe動詞は入れるべきか否か
『設計というのは名前が決まればだいたい終わったようなもの』教の私としては、名前付けには何よりもこだわりたい。
そうしていたところ、ツイッターのエラーメッセージがなかなかバリエーションに富んでいることに気付いたので、今後の参考になればと思い、エラーメッセージの特徴をまとめてみた。
紹介するエラーメッセージは Twitter API および Twitter gem から引用しています
引用しているエラーメッセージは Twitter API のレスポンスに含まれるものです。引用しているエラークラス名は Twitter gem で定義されているものです。
紹介しているエラーメッセージとエラークラス名は、一例としてRubyで下記のように使用されます。
begin
api_client.request_something
rescue Twitter::Error::Unauthorized => e
puts "##{e.class}, #{e.message}"
end
# => Twitter::Error::Unauthorized, Invalid or expired token.
該当するRubyコードやドキュメントのURLは下記の通りです。
認証に失敗している系のエラー
クラス名はTwitter::Error::Unauthorizedとなる。
Invalid or expired token.
トークンの有効期限が切れている場合。先頭は大文字、フレーズのみ、ピリオドで終わるというパターン。
You have been blocked from viewing this user's profile.
ブロックされているユーザーのプロフィールを見ようとした場合。がっつり文章パターン。
Could not authenticate you.
何らかの理由でOAuthに失敗している場合。文章で主語が省略されている。
文法としては正しくないが、gitのcommitメッセージも主語が省略されることが多く、少なくともエンジニア関係の文章に限るとこの書き方でもよいらしい。
Not authorized.
理由は分からないが極稀にでる認証のエラー。こんなに短くてもピリオドがあった方がよいらしい。
アカウントが凍結されている系のエラー
クラス名はTwitter::Error::Forbiddenとなる。
User has been suspended.
ユーザーが凍結されている場合。文章かつ現在完了（継続）用法を使っている。
非ネイティブが書くには「長すぎるかな？」と躊躇しそうな文章だが、これでもよいらしい。（今は慣れたので自分でもこう書く）
Your account is suspended and is not permitted to access this feature.
凍結されているユーザーの認証情報を使って何かしらのAPIにアクセスした場合。andで文章をつないでいる。
これ私にも長過ぎるように思えるが、理由が2つあるのでこれでもよいらしい。（これも慣れた）
You are unable to follow more people at this time. Learn more <a href='http://support.twitter.com/articles/66885-i-can-t-follow-people-follow-limits'\>here\.
単位時間あたりにフォローできる数の制限を超えた場合。文章かつHTMLタグ付き。
かなり前衛的だが、このエラーについての質問が多いと想定される場合はこれでもよいのかもしれない。
To protect our users from spam and other malicious activity, this account is temporarily locked. Please log in to https://twitter.com to unlock your account.
理由が不明だがたまにでるエラー。かなり長めの文章かつURL付き。
こっちはHTMLタグにはなっていない。ツイッター社の中でもエンジニアによってエラーメッセージの書き方に幅があるんだろうか。
You can't follow yourself.
自分のIDをフォローしようとした場合。ここまで読み進めている人にはもう見慣れたエラーメッセージになっているはず。
Could not determine source user.
ユーザー間の相互関係を変更するAPIでソースユーザーが見付からなかった場合。これももはやよくある形。
You cannot send messages to users you have blocked.
自分がブロックしているユーザーにDMを送ろうとした場合。can'tではなくcannotを使っている。省略形にするかどうかはどちらでもよいらしい。
You cannot send messages to users who are not following you.
自分のフォローしていないユーザーにDMを送ろうとした場合。関係代名詞を使うパターン。
これも非ネイティブの私が書く時は「長すぎるかな？」と躊躇してしまうが、へたに省略して対象が誰なのか分からなくなるよりはこの方がよいのだろう。
You are sending a Direct Message to users that do not follow you.
自分をフォローしていないユーザーにDMを送ろうとした場合。
直前のエラーメッセージとこのエラーメッセージを見比べた後なら、確かに関係代名詞以降の文章まで正確に書いた方がよいかも、と思わせられる。（もし書かなかったら紛らわし過ぎるので）
The text of your direct message is over the max character limit.
ユーザーが見付からなかった系のエラー
クラス名はTwitter::Error::NotFoundとなる。
User not found.
ユーザーをlookupしようとして見付からなかった場合。これに限らず、not foundは後置のパターンをよく見かける気がする。
余談だが、似たような例としてtoo many requestsは前置、rate limit exceededは後置という違いがある。単語によるものの、過去分詞で名詞を修飾する場合のエラーメッセージは後置になるらしい。（ただし例外も後述される）
No user matches for specified terms.
複数ユーザーのlookupを一括でしようとしたが1人もユーザーが見付からなかった場合。
termには様々な意味（後述）があるので非ネイティブとしてはこの単語は選びづらいが、少なくともこういう場合にも使える単語らしい。
termの意味の例
期間、期限、用語、条件（terms of use == 利用規約）
Sorry, that page does not exist.
何かしらのリソースが見付からなかった場合。ひとまず一言謝っておく時は先頭にSorry,と付けておけばよいらしい。
サーバーのキャパシティを超えてしまった系のエラー
クラス名はTwitter::Error::ServiceUnavailableとなる。
Over capacity
理由はよく分からないがたまにでるエラー。シンプルなフレーズかつピリオドがないパターン。
（エラーメッセージなし）
同じエラークラスで、エラーメッセージが空の場合がたまにある。エラークラス名で理由が十分に伝わる場合はこれでもよいらしい。
その他のエラークラス名
Twitter gemには他にもたくさんのエラーが定義されている。エラークラス名として参考になるのでそれらも引用しておく。code
RequestEntityTooLarge
「too + 形容詞」が後置になっているパターン。TooManyRequestsというエラークラス名もある。この2つから察する限り、どっちでもよいんだろうか？
AlreadyFavorited
「既に何かしら処理が終わっている」というエラーの場合、クラス名には「have + 過去分詞」は付けないらしい。
AlreadyRetweeted
これも上記の例と同様だが、エラーメッセージが少し特殊で、
sharing is not permissible for this status (Share validations failed)
となっている。先頭が大文字じゃない、かつ、カッコ書きでより具体的な理由が書かれている。このエラーメッセージだけ違う人が書いたんだろうか。
「カッコ書きで理由を書くことの是非」について、これまでの例を見る限りカッコ書きはあまり一般的ではないらしい。ひとまず私は滅多に使わないようにしている。
DuplicateStatus
この場合のエラーメッセージは、
Status is a duplicate.
となっている。duplicateが形容詞に思えるが、この場合は名詞の用法もあるらしい。重複した処理を許さない場合のエラーメッセージとして使えるかもしれない。
その他のエラー定数名
Twitter gemに定義されているエラー定数名から参考になりそうなものをいくつかピックアップ。code
UNABLE_TO_VERIFY_CREDENTIALS
何かができない場合は「unable to 動詞」でよいらしい。ちょっと長いようにも思えるのでご参考まで。
CANNOT_MUTE
何かができない場合のもっとシンプルな書き方はこちら。
OAUTH_TIMESTAMP_OUT_OF_RANGE
何かが範囲外であるという状況はよく見かけるが、そういう場合はこの書き方でよいらしい。
まとめ
質問何でもどうぞ！