メッセージの作成スタイル

明瞭な書き方は、メッセージの変換を助けます。 メッセージの作成スタイルに関する以下の指針には、用語、句読点、叙法、態、 時制、大文字、形式、およびその他の使用上の問題点が含まれます。

  • 簡潔なメッセージを作成する。 望ましいのは、1 つの文のメッセージです。
  • 完全文形式を使用する。
  • あいまいさを除く必要があるときは、冠詞 (a、an、the) を追加する。
  • 文の最初のワードを大文字ではじめ、文の終わりにピリオドを使用する。
  • 現在形を使用する。 メッセージには未来形は使用しないでください。 例えば、次の文を使用します。 
    The cal command displays a calendar.
    次の文は使用しません。 
    The cal command will display a calendar.
  • メッセージでは一人称 (I または we) は使用しない。
  • ヘルプ・テキストや対話式テキスト以外では、二人称 (you) の使用を避ける。
  • 能動態を使用する。 次の例は、受動態で書かれたメッセージを、どのように能動態のメッセージに戻せるかを示しています。 
    Passive: Month and year must be entered as numbers.
Active:  Enter month and year as numbers.
  • 命令法 (コマンド句) および能動動詞 (specify、use、check、choose、 および wait などの) を使用する。
  • メッセージを肯定語調で述べる。 以下に、否定的メッセージを肯定的にした例を示します。
    Negative: Don't use the f option more than once.
Positive: Use the -f flag only once.
  • ワードは、辞書にある文法上のカテゴリーでのみ使用する。 名詞でのみ表されるワードは、動詞としては使用しないでください。 例えば、「問題をソリューション (solution) する」や 「システムをアーキテクト (architect) する」などは使用しないでください。
  • 接頭部も接尾部も使用しない。 変換プログラムは、re-、un-、in-、 あるいは non- で始まるワードの意味が分からない場合があり、 接頭部もしくは接尾部を使用したメッセージの変換が、意図する意味にならないことがあります。 この規則に例外が生ずるとすれば、接頭部が、 使用頻度の高いワードの必須の要素である場合です。 例えば、previous と premature のワードは受け入れられますが、 nonexistent は受け入れられません。
  • 単数または複数を示す括弧は使用しない。 例えば、error(s) の括弧は変換できません。 単数および複数を示す必要がある場合は、error or errors と書きます。 ワードの単数または複数の必要の有無によって、異なるメッセージが出されるように、 コードを変えることもできます。
  • 短縮形は使用しない。
  • 引用符は、単一引用符も二重引用符も使用しない。 例えば、%s、 %c、 および %d などの変数の周囲、 またはコマンドの周囲には引用符を使用しないでください。 ユーザーが、引用符を文字通りに解釈する可能性があります。
  • 行の終わりのワードにハイフンを付けない。
  • メッセージでは、標準の強調表示指針を適用せず、頭文字または大文字を他の強調表示方法で置き換えることはしない。 (標準の強調表示には、 コマンド、サブルーチン、およびファイル用の太字、 変数やパラメーター用のイタリック、 例や表示テキスト用のタイプライター書体または Courier フォントのような指針が含まれます。)
  • and/or の構造は使用しない。 このような構造は、他の言語には存在しません。 通常、両方を行う必要がないことを示す場合は、 or のほうが適切な表現です。
  • 24 時間クロックを使用する。 時刻の指定に a.m. または p.m. を使用しないでください。 例えば、1:00 p.m. は 1300 と書きます。
  • 頭字語は避ける。 頭字語の使用は、完全なスペルの用語より読者にとって分かりやすい場合に限ります。 頭字語を複数形にする場合は、アポストロフィを付けずに小文字の s を追加します。 頭字語は、使用の前に、商標でないことを確認してください。
  • メッセージを文節から作成しない。 プログラム内でフラグまたは他の手段を使用して情報を伝え、 完全なメッセージが適切な時点で出されるようにします。
  • ハードコーディングされたテキストを、メッセージ内の %s ストリングの変数として使用しない。
  • メッセージの最後の行を ¥n (改行を示す) で終了する。 これは、1 行メッセージにも該当します。
  • 2 番目以降の行を ¥t (タブを示す) で始める。
  • 他のすべての行を ¥n¥ (改行を示す) で終了する。
  • 必要ならば、ワード境界で強制的に改行し、 メッセージ・ストリングの表示を受け入れられるようにする。 printf サブルーチンは、しばしば、 メッセージ・テキストの表示に使用されますが、ワード境界を無視し、 ときにはワードを中央で分割してテキストを必要に応じて折り返します。
  • なんらかの理由で、メッセージを改行文字で終えてはならない場合は、 作成者にその趣旨のコメントを残す。
  • 各メッセージの前に、メッセージを呼び出したコマンドの名前を付け、 その後にコロンを付ける。 次の例は、コマンド名が入っているメッセージです。 
    OPIE "my_example: Opening the file."
  • システムが過負荷にならない限り、 ユーザーに後で再試行してくださいと指示しない。 再試行の必要は、メッセージから明白なはずです。
  • コマンド・ラインのテキストを記述するときは、 parameter (パラメーター) という語、 数値データを示す場合は、value (値) という語、 パラメーターとともにコマンドを記述する場合は、 command string (コマンド・ストリング) という語を使用する。
  • 値の 3 桁ごとの桁区切りのコンマは使用しない。 1,000 ではなく 1000 を使用してください。
  • メッセージを * (アスタリスク) で強調する必要がある場合には、 メッセージの先頭と終わりに 2 つずつのアスタリスクを付ける。 例: 
    ** Total **
  • log in (ログインする) や log off (ログオフする) という語は動詞として使用する。 例えば、次のようになります。 
    Incorrect: Choose the appropriate method for system log in.
Correct: Choose the appropriate method to log in to the system.
  • user name (ユーザー名)、group name (グループ名)、 および login (ログイン) という語は名詞として使用する。 例: 
    The user is sam.
The group name is staff.
The login directory is /u/sam.
  • superuser (スーパーユーザー) という語は使用しない。 root ユーザーにすべての特権があるとは限らないことに注意してください。
  • 適用できるならば、以下の発生頻度の高い標準のメッセージを使用する。
    望ましい標準メッセージ あまり望ましくないメッセージ
    Cannot find or open the file. Can't open filename.
    Cannot find or access the file. Can't access.
    The syntax of a parameter is not valid. Syntax error.