エラーメッセージのスタイルガイドこのスタイルガイドでは、PostgreSQLで生成されるすべてのメッセージに対する、一貫性維持、ユーザに親切なスタイルについての希望を説明します。何がどこで起こったか主メッセージは、簡潔に事実を示すものにすべきです。特定の関数名など実装の詳細への参照は止めるべきです。"簡潔"は"ごく普通の条件下で1行に収まる"ことを意味します。主メッセージを簡潔にするために必要であれば、また、特定のシステムコールが失敗したなど実装の詳細について記載したいのであれば、詳細メッセージを使用してください。主メッセージ、詳細メッセージの両方は事実を示すものにすべきです。すれば問題を解決できるかに関する提言には、その提言が常に適切とは限らない場合は特に、ヒントメッセージを使用してください。hint)ではなく、以下のように記述してください。主メッセージを簡潔にすることは、要点を維持することを助けます。クライアントは、エラーメッセージ用に1行文確保すれば十分であるという仮定の元で画面設計を行なうことができます。詳細メッセージやヒントメッセージを冗長モードに格下げしたり、エラーの詳細を表示するウィンドウをポップアップさせることもできます。詳細メッセージやヒントメッセージは通常ディスク容量を節約するためにサーバログには出力されません。ユーザはどうやってもその詳細を知りませんので、実装の詳細への参照を避けることが最善です。整形メッセージテキストの整形に関して、特定の前提を行なわないでください。クライアントやサーバログでは、自身の必要性に合わせて行を改行すると想定してください。長めのメッセージでは、改行文字(\n)を推奨する段落の区切りを示すものとして使用しても構いません。メッセージの終りに改行を付けないでください。タブや他の整形用文字を使用しないでください。(エラーの内容の表示では、関数呼出しなどのコンテキストのレベルを区切るために、改行が自動的に追加されます。メッセージは必ずしも端末型のディスプレイに表示されるとは限りません。GUIのディスプレイやブラウザでは、こうした書式指示はよくて無視されます。英文では、引用が適切な場合には二重引用符を使用すべきです。他の言語でのテキストは、出版上の慣習や他のプログラムのコンピュータ出力と矛盾しない種類の引用符の1つを一貫して使用してください。二重引用符と単一引用符の選択はどちらかでもよいものですが、推奨する方がよく使われています。二重引用符)に従って、オブジェクトの種類に応じて引用符を選択することを推奨する人もいます。これは言語内部の技術的な事項であり、多くのユーザが理解できるものではありません。他の種類の引用手法には拡張できません。他の言語へ翻訳できません。引用符の使用ファイル名、ユーザ提供の識別子、複数の単語を含む変数を区切るために引用符を使用してください。複数の単語を含まない変数(例えば演算子名)には引用符を使用しないでください。バックエンドには必要に応じて出力に二重引用符を付与する関数(例えばformat_type_be())があります。した関数の出力の周りには引用符を追加しないでください。オブジェクトの名前をメッセージ内に埋め込む際に曖昧さが生じることがあります。埋め込む名前がどこから始まりどこで終るかついての表記には一貫性を持たせてください。不必要にメッセージをまとめたり、引用符を二重にすることは止めてください。文法と句読点この規則は、主エラーメッセージと詳細/ヒントメッセージとで異なります。最初の文字を大文字にしないでください。メッセージの最後にピリオドをつけないでください。メッセージの終りに感嘆符をつけようとは考えないでください。完全な文章を使用し、終りにピリオドを付けてください。文章は大文字から始めてください。句読点の禁止により、クライアントアプリケーションでは、そのメッセージを各種文法的なコンテキストに埋め込み易くなります。主メッセージはしばしば文法的に完全な文章になっていません。(そして、1行以上の長さになりそうであれば、主メッセージと詳細メッセージに分割すべきです。詳細メッセージとヒントメッセージは、より長く、かつ複数の文章を持つ必要があるかもしれません。一貫性のため、これらは、たとえ文章が1つだけであっても、完全な文章形式に従うべきです。大文字と小文字メッセージの言葉使いでは小文字を使用してください。主エラーメッセージの場合は先頭文字も含みます。SQLコマンドとキーワードがメッセージ内に出現する場合は大文字を使用してください。メッセージは完全な文章かもしれませんし、そうではないかもしれませんので、この方法は、より簡単にすべての見ための一貫性を向上します。能動態を使用してください。Bを行なうことができない")場合は完全な文章を使用してください。主語がプログラム自体である場合は、主語を付けずに電報様式を使用してください。プログラムに"I(私)"を使用しないでください。プログラムは人間ではありません。他を真似ないでください。試行が失敗したが、次は(何らかの問題を修正した後に)成功するかもしれない場合は過去形を使用してください。失敗が永続するようであれば、現在形を使用してください。以下の2つの意味には無視できないほどの違いがあります。"%s"最初のものは、ファイルを開くことに失敗したことを意味します。メッセージには、"ディスクが一杯"とか"ファイルが存在しない"といった、その理由を付けるべきです。次回はディスクに空きがあるかもしれませんし、問題のファイルが存在するかもしれませんので過去形が適切です。2番目の形式は、そのプログラム内の指名されたファイルを開く機能が存在しない、あるいは、概念的に不可能であることを示します。この条件は永遠に続きますので現在形が適切です。仮定ですが、一般的なユーザは単なるメッセージの時制から多くを意味を引き出すことはできないでしょう。言語が文法を提供してくれますので、それを正確に使用すべきでしょう。オブジェクトの種類オブジェクトの名前を引用する時、そのオブジェクトの種類を記載してください。ないと、"foo.bar.baz"が何なのか誰もわかりません。角括弧は、(1)コマンドの概要にて省略可能な引数を表す、(2)配列の添字を表す、ためだけに使用されます。広く知られる慣習に対応するものがなく、人々を混乱させることになります。エラーメッセージの組み立てメッセージに、他で生成されるテキストを含める場合、以下の様式で埋め込んでください。すべての起こり得るエラーコードを単一のなめらかな文章に埋め込むことを考えることは困難です。何らかの句読点が必要とされます。括弧の中にテキストを埋め込むこともまた推奨されていましたが、よくある埋め込むテキストがそのメッセージの最も重要となる場合は不自然です。エラーの理由メッセージは常にエラーが発生した理由を記述すべきです。failure)理由がわからない場合は、コードを直すべきです。関数名エラーテキストには、それを報告したルーチンの名前を含めないでください。必要に応じて、そのルーチンを見つける他の機構があり、また、ほとんどのユーザにとって役に立つ情報ではありません。関数名がないと、エラーメッセージにあまり意味がないのであれば、言葉使いを替えてください。"z"同時に呼び出した関数名の記述も止めてください。代わりにそのコードが何をしようとしたのかを記述してください。%mもし本当に必要であれば、詳細メッセージにそのシステムコールを記載してください。(詳細メッセージの情報としてシステムコールに実際に渡した値を与えることが適切な場合もあります。ユーザはその関数が何を行なうのかを知りません。"Unable"はほとんど受動態です。not"の適切な方を使用してください。result"といったエラーメッセージは、知的に解釈することが非常に困難です。format"を記述してください。"Illegal"は規則違反を表します。他は"invalid"です。良くするために、なぜ無効なのかについても記述してください。"unknown"は極力使用しないでください。response"について考えてみましょう。どんな応答であるかわからなければ、どうやって何がエラーなのかわかるでしょうか。"Unrecognized"を選んだ方が良い場合がしばしばあります。その警告の中に値が含まれていることを確認してください。プログラムがリソースの場所(例えばパスの検索)について無視できないアルゴリズムを使用し、そのアルゴリズムが失敗した場合、プログラムがリソースを"find"できなかったと記述すべきでしょう。想定したリソースの場所はわかっているが、プログラムがアクセスできなかった場合は、リソースが"exist"しなかったと記述してください。この場合に"find"を使用すると、弱くとられ、問題が混乱します。適切なスペル単語の完全なスペルを使用してください。以下は止めてください。これは一貫性を向上します。地域化エラーメッセージは他の言語に翻訳される必要があることを忘れないでください。項46.2.2のガイドラインに従い、翻訳者に苦労を強いることを防いでください。