どのようにして良いエラーメッセージを書くのですか？
これはコーディングの問題というよりは書記言語の問題ですが、クライアントや他の誰かからコピーが提供されない状況では、プログラマーがしなければならないことです。良いか悪いかにかかわらず、エラーメッセージの例があれば、それを強調することを歓迎します。
簡単に検索したところ、重複したスレッドが見つかりませんでした。わかりました、どうぞ。皆さんありがとう。
- お詫び申し上げます。
- 何が悪かったのか言ってください。
- それを解決する方法を言います。
- 礼儀正しくしてください。
- メッセージは、アプリケーションが問題の責任を受け入れるように表現する必要があります。ユーザーを非難したり批判したり、自分のせいだと思わせたりしないでください。
例：
「申し訳ありませんが、ファイルを開くことができませんでした。ファイルが別のプログラムによってまだ開かれていないことを確認して、再試行してください。」
エラー番号や開発者だけが理解できる何かなど、ユーザーを怖がらせる追加の詳細がある場合は、それらを表示しないでください。それらをログファイルに書き込むか、それらにアクセスするために押すことができる詳細ボタンを用意します。
メッセージボックスまたは画面にエラーメッセージを表示することについて話していると思います。
ユーザー向けですか、それとも管理者/開発スタッフのログファイルにありますか？
一般的に、これらは重要だと思います。
- タイムスタンプ
- 重大度レベル
- 何うまくいかなかった
- 「行動を起こす必要がありますか？」という質問に答えてください。そして「もしそうなら、どんな行動？」
- 開発レベルの詳細（ユーザー向けの場合は目立たない）
- 一貫した形式と用語
これらはすべて重要だと思いますが、聴衆によって目立ちが変わります（dmckeeが指摘しているように）。もう1つのヒント（一般的に）は、5つのW（誰が、何を、...など）に答えることです。
私はソフトウェアセキュリティ会社で働いているので、私の答えは上記の答えのいくつかとは大幅に異なる場合があります。
エラーメッセージに直面する良いユーザーは次のとおりです。
一般的なものと具体的なもののバランスをとる-エラーを修正して先に進むのに十分な情報をユーザーに提供する必要がありますが、攻撃者がこれらの同じエラーメッセージを使用してサイトを攻撃する可能性があることに注意してください。この良い例は、「ユーザーjoeのパスワードが正しくありません」または「userjoeはこのシステムに存在しません」というエラーメッセージが返されるログインコントロールです。これは、攻撃者に正しいユーザーを発見する道を進んでいることを知らせます。ユーザー名もパスワードも持っていない場合、どちらが戦いの半分になります。
何が悪かったのかをユーザーに伝えます。これも、一般的なものと特定のものの間でバランスが取れています。ユーザーはODBCエラーメッセージを表示する必要はありませんが、エラーがあなたのせいであり、数分後に再試行する必要があることを知っておくと役立つ場合があります。ユーザーに何を伝えますか彼らは助けることができます-あなたがバックエンドロギングシステム（あなたがすべきだ）を持っているなら、あなたが役に立つと思うすべてを記録し、そしてあなたがあなたに電話または電子メールを送ってあなたに正確に伝えることができるようにあなたがユーザーに提供できるIDを生成します再現手順：エラーが発生したときにバグ送信フォームを公開することで、これを自動化することもできます。
一貫性を保つ–エラールックアップテーブルを使用して、すべてのエラーが同じであり（同じ問題に対して）、適切に記述されていることを確認します。誤字脱字、スペルミス、文法エラーは、本番ソフトウェアでは許容できません。
エンドユーザーの場合：ユーザーに何をすべきかを伝えます。ユーザーが入力値を変更するか、5分後に再試行するか、サポートに連絡する必要がありますか？
適切なエラーメッセージには、次の3つの部分があります。
- 問題-エラーが発生したことを説明します。
- 原因-問題の原因を説明します。
- 解決策-問題を克服する方法を説明します。
エラーメッセージを書いたり確認したりする場合は、最初にこれら3つのポイントを書くことに焦点を合わせます。メッセージが非常に長い場合でも、最初に書くときは心配しないでください。いつでも戻って後で単純化することができます。
しかし、その逆は真実ではありません。小さなメッセージを、問題、原因、問題の解決策を明確に説明するメッセージに形作ることは困難です。あなたはメッセージが小さいままであることを確実にするためにあなたの考えを絶えず編集しているでしょう、そしてある時点であなたはブロックされるでしょう。はい、私はその問題を数回経験したので、それがどれほど難しいかを知っています。
メッセージにこれら3つの部分がすべて含まれていることを確認したら、メッセージを確認します。それを確実にするためにそれを編集する必要があります：
- ユーザー中心-専門用語や、視聴者が理解しにくい言葉は避けてください。
- 直接です-ウィリアム・ストランクが言ったように、飼いならされた、無色の、躊躇し、コミットメントのない言葉は避けてください。
- 不要な単語を省略します-カット、カット、カット。
ご覧のとおり、このフレームワークは単純であり、あまり考慮する必要はありません。
出典：
明らかに、エラー防止が最善です。タスクを正常に完了するために十分な手がかりを常にユーザーに提供します（つまり、データ入力フィールドに必要なフォーマットを説明します）。ただし、「間違いを犯すのは人間です...」そして（Webアプリケーションのエラーにユーザビリティの原則を適用することによって）許しが目標です。
エラーメッセージには3つの重要な機能があります：
1。注意を引く-まず、効果を確実にするために、ユーザーはそれを見る必要があります
- 赤色）
- フォント（サイズ、重さ）
- 場所（ページ上部、アラートボックス）
- フォーカス（！記号、入力ボックスの概要）
- 一貫性（アプリケーション全体のエラーメッセージに同様の形式を使用）
2。エラーの説明-何が悪かったのかをユーザーに通知します
- ユーザーが理解できるわかりやすい言葉を使用する
- 客観的な声を使用し、ユーザーを責めないでください
- 簡潔にする
。回復を提案する-エラーを修正して続行するための有用な提案を与える
- ユーザーがこれまでに完了したものをすべて保存します
- それを修正するために必要な作業を減らす
- ログインしたユーザーの場合、タイムアウト時に再認証を許可する
そうは言っても、私は何かをより詳細に、特に良いエラーメッセージと悪いエラーメッセージの例を使ってコンパイルしたいと思います。
良いエラーメッセージを書くために、あなたはそれぞれの聴衆について考える必要があります。オーディエンスを理解すると、エラーメッセージの設計がはるかに簡単になります。
まず、エンドユーザーメッセージの要件：
- タスクを実行したい
- 問題ではなく解決策について知りたい
- エラーメッセージを実際に見たり読んだりしたくない。
次に、サポート技術者メッセージの要件：
- 反応的ではなく、積極的になりたい
- 「レンガの壁」の問題にぶつかりたくない
- メッセージが殺到したくない。
最後に、サポート開発者メッセージの要件：
- コードを使用するための単純なメンタルモデルが必要
- コンポーネントが「正常に機能する」ことを期待します
- うまくいかないときに役立つ情報が必要です。
エンドユーザーにとっては非常に悪いが、開発者にとっては合理的かもしれないエラーメッセージの例は、「レイテンシキャッシュがアウトバウンドヘッダーと衝突した」です。 :-)
すでに言われたことに、私は追加します：
- パスワードなど、セキュリティ上のリスクとなる可能性のあるメッセージを表示しないでください。これは、逆コンパイルによってそのようなものがまだ利用できない場合、Webアプリにとって特に重要です。
- まだ執拗な文法やスペルの専門家でない場合は、ユーザーに表示されるすべてのテキストを校正してください。
ユーザーに何をすべきかを伝えることができる場合は、プログラムで行うことを検討してください。私の意見では、エラーメッセージは、プログラムが何をすべきかについて疑問がある場合にのみ表示されるべきです。なぜ失敗することにしたのか考えてみてください。おそらく、回復しようとする責任を負わないのでしょうか。たぶん、ユーザーはそれをはるかに簡単に行うことができますか？たぶん、ユーザーはどの解決策を取るかを決める必要がありますか？多分あなたはそれが決して起こらないと思ったでしょう（この場合はサポートまたはプログラマーに連絡するようにユーザーに伝えることを忘れないでください）？
神経系に損傷を与える可能性があるのは、エラーメッセージでWordORが使用されている場合です。 "ファイルが見つかりませんOR許可なしORディスクがいっぱいですORあなたの犬はひどい頭痛がしますOR ..." A user 本当に考えられるエラーの原因のどれが起こったかを知る必要があります。プログラマーはエラーメッセージのORを避けてください。
エラーメッセージをコードの別の場所にコピーしないでください。ユーザーがプログラム内のメッセージを見てフィードバックを送信する場合、より幸運なのは、エラーメッセージの意味を理解できる場合です。それほど幸運ではないケースは、少なくともソースコード全体をgrepして、プログラムがクラッシュした場所を見つけることができるということです。同じメッセージを複数の場所で見つけた場合、自分自身を助けることはできません。
ああ、起こりうる結果について言及することを忘れないでください：「リス防止システムは動作を停止します。ハードディスクに保存されているものはすべてリスによってランダムに変更される可能性があります。」 「リス防止システムは機能を停止します。代わりに、一般的な防止フレームワークによってリスが防止されます。」厳しさには違いがあります。
エラーメッセージはエンドユーザー向けであり、コードを維持する必要があるユーザー向けでもあります
まずエンドユーザーに、何をすべきかを伝えます。これは、Enterキーを押すだけで、続行、再試行、閉じて再起動、PCの再起動を行うことができます。
メンテナにとって2番目に、エラーに関する情報をできるだけ多く含めます。決して多すぎることはありません。私は個人的に、エラーメッセージではなくログファイルを好みます。さらに良いのは、エンドユーザーがアプリケーションからログの内容を電子メールで送信する方法を含めることです。
エラーメッセージは次のようになります。
- エラーの原因を具体的に説明してください。
- エラーを修正するための提案を提供します。
- 平均的なユーザーを混乱させるような言葉は使用しないでください。
テクニカルサポートの観点から、エラーメッセージが一意であることも重要です。ユーザーが同じ「ファイルを開くことができませんでした」エラーを6つの異なる方法で生成できる場合、テクニカルサポート担当者がユーザーが何をしているかを正確に把握することは困難です。したがって、エラーメッセージは、エラーの種類ごとに一意である必要があり、可能であればエラーコードまたは番号を指定して、サポート担当者が問題の場所を把握できるようにします。
エラーメッセージにエラーコードが含まれていると、テクニカルサポートに役立つことがわかりました。ユーザーがサポート担当者にエラーメッセージを報告すると、口頭のエラーメッセージを混同したり、誤って報告したりすることがよくあります。ただし、メッセージにエラー番号が含まれている場合は、「レポートを印刷しようとしたときに8512エラーが発生しました」など、正確なエラーを報告するのに非常に優れています。
可能であれば、エラーのログを保持することも役立ちます。多くの場合、ユーザーは特定の操作を試みたときにエラーを報告しますが、エラーが何であったかを正確に覚えていません。テクニカルサポート担当者が参照できるエラーログがある場合は、問題の特定がはるかに簡単になります。
エラーケースの99.9％でユーザーを支援するため、通常、問題の一般的な理由を指摘する価値があります。
たとえば、初期化の問題には2つの方向性があります。次のような構成例外が発生します。
「認識された例外が発生しました。これは構成に問題がある可能性があります」
予期しないもののための別のもの：
「予期しないエラーが発生しました。」
次に、設定（開発スイッチのオンまたはオフ）に応じて、開発情報またはよりエンドユーザーフレンドリーな情報を出力します。
ここで注意すべきいくつかの異なるコンテキストがあります（これは何度も何度も言及されていると確信していますが）：
1）「おっと、何か悪いことが起こった」というメッセージを表示する必要があるWebサイトについて話している場合は、エラーが発生したことをユーザーに伝える簡単な言葉が必要です。もう一度やり直してください。それでも問題が解決しない場合は、何とか何とか何とか...
2）システム管理者と開発者が読み取るためにコードでスローされた例外をログに記録することについて話している場合、問題は、ログファイル、電子メール、またはイベントのいずれかに記録される例外のメッセージとスタックトレースを取得することです。誰かがこれを調べることがどれほど緊急であるかに応じて異なる方法で処理できるように、ビューア。
3）例外のメッセージを書くことについて話している場合、私の提案は、どのような種類のエラー条件が満たされたのかを明確に記録することです。存在してはならないnull参照があるか、存在するはずのファイルが欠落しているなど、エラーの重大度とともにさらに悪いものがありますか。アプリケーションは実行を継続できますか、それともこの状態でエラーページに戻る必要があります。
何よりも、エンドユーザーは技術的な本質を気にしないことを忘れないでください。それが機能するかどうかだけ。それが機能しないとき、彼または彼女は彼らがやろうとしていることへのその影響だけを気にします。有用なエラーメッセージは、 何、ではなく なぜ。
ユーザーの見通しから。