sources.sgml

PostgreSQL 8.1.4的源码 适用于Linux下的开源数据库系统

    aren't even familiar with, it won't scale to other kinds of quoted terms,
    it doesn't translate to other languages, and it's pretty pointless, too.
   </para>

  </simplesect>

  <simplesect>
   <title>Use of quotes</title>

   <para>
    Use quotes always to delimit file names, user-supplied identifiers, and
    other variables that might contain words.  Do not use them to mark up
    variables that will not contain words (for example, operator names).
   </para>

   <para>
    There are functions in the backend that will double-quote their own output
    at need (for example, <function>format_type_be</>()).  Do not put
    additional quotes around the output of such functions. 
   </para>

   <para>
    Rationale: Objects can have names that create ambiguity when embedded in a
    message.  Be consistent about denoting where a plugged-in name starts and
    ends.  But don't clutter messages with unnecessary or duplicate quote
    marks. 
   </para>

  </simplesect>

  <simplesect>
   <title>Grammar and punctuation</title>

   <para>
    The rules are different for primary error messages and for detail/hint
    messages:
   </para>

   <para>
    Primary error messages: Do not capitalize the first letter.  Do not end a
    message with a period.  Do not even think about ending a message with an
    exclamation point. 
   </para>

   <para>
    Detail and hint messages: Use complete sentences, and end each with
    a period.  Capitalize the first word of sentences.
   </para>

   <para>
    Rationale: Avoiding punctuation makes it easier for client applications to
    embed the message into a variety of grammatical contexts.  Often, primary
    messages are not grammatically complete sentences anyway.  (And if they're
    long enough to be more than one sentence, they should be split into
    primary and detail parts.)  However, detail and hint messages are longer
    and may need to include multiple sentences.  For consistency, they should
    follow complete-sentence style even when there's only one sentence. 
   </para>

  </simplesect>

  <simplesect>
   <title>Upper case vs. lower case</title>

   <para>
    Use lower case for message wording, including the first letter of a
    primary error message.  Use upper case for SQL commands and key words if
    they appear in the message.
   </para>

   <para>
    Rationale: It's easier to make everything look more consistent this
    way, since some messages are complete sentences and some not.
   </para>

  </simplesect>

  <simplesect>
   <title>Avoid passive voice</title>

   <para>
    Use the active voice.  Use complete sentences when there is an acting
    subject (<quote>A could not do B</quote>).  Use telegram style without
    subject if the subject would be the program itself; do not use
    <quote>I</quote> for the program.
   </para>

   <para>
    Rationale: The program is not human.  Don't pretend otherwise.
   </para>

  </simplesect>

  <simplesect>
   <title>Present vs past tense</title>

   <para>
    Use past tense if an attempt to do something failed, but could perhaps
    succeed next time (perhaps after fixing some problem).  Use present tense
    if the failure is certainly permanent. 
   </para>

   <para>
    There is a nontrivial semantic difference between sentences of the form
<programlisting>
could not open file "%s": %m
</programlisting>
and
<programlisting>
cannot open file "%s"
</programlisting>
    The first one means that the attempt to open the file failed.  The
    message should give a reason, such as <quote>disk full</quote> or
    <quote>file doesn't exist</quote>.  The past tense is appropriate because
    next time the disk might not be full anymore or the file in question may
    exist. 
   </para>

   <para>
    The second form indicates the the functionality of opening the named file
    does not exist at all in the program, or that it's conceptually
    impossible.  The present tense is appropriate because the condition will
    persist indefinitely. 
   </para>

   <para>
    Rationale: Granted, the average user will not be able to draw great
    conclusions merely from the tense of the message, but since the language
    provides us with a grammar we should use it correctly. 
   </para>

  </simplesect>

  <simplesect>
   <title>Type of the object</title>

   <para>
    When citing the name of an object, state what kind of object it is.
   </para>

   <para>
    Rationale: Otherwise no one will know what <quote>foo.bar.baz</>
    refers to.
   </para>

  </simplesect>

  <simplesect>
   <title>Brackets</title>

   <para>
    Square brackets are only to be used (1) in command synopses to denote
    optional arguments, or (2) to denote an array subscript.
   </para>

   <para>
    Rationale: Anything else does not correspond to widely-known customary
    usage and will confuse people.
   </para>

  </simplesect>

  <simplesect>
   <title>Assembling error messages</title>

   <para>
   When a message includes text that is generated elsewhere, embed it in
   this style:
<programlisting>
could not open file %s: %m
</programlisting>
   </para>

   <para>
    Rationale: It would be difficult to account for all possible error codes
    to paste this into a single smooth sentence, so some sort of punctuation
    is needed.  Putting the embedded text in parentheses has also been
    suggested, but it's unnatural if the embedded text is likely to be the
    most important part of the message, as is often the case. 
   </para>

  </simplesect>

  <simplesect>
   <title>Reasons for errors</title>

   <para>
    Messages should always state the reason why an error occurred.
    For example:
<programlisting>
BAD:    could not open file %s
BETTER: could not open file %s (I/O failure)
</programlisting>
    If no reason is known you better fix the code.
   </para>

  </simplesect>

  <simplesect>
   <title>Function names</title>

   <para>
    Don't include the name of the reporting routine in the error text. We have
    other mechanisms for finding that out when needed, and for most users it's
    not helpful information.  If the error text doesn't make as much sense
    without the function name, reword it. 
<programlisting>
BAD:    pg_atoi: error in "z": can't parse "z"
BETTER: invalid input syntax for integer: "z"
</programlisting>
   </para>

   <para>
    Avoid mentioning called function names, either; instead say what the code
    was trying to do:
<programlisting>
BAD:    open() failed: %m
BETTER: could not open file %s: %m
</programlisting>
    If it really seems necessary, mention the system call in the detail
    message.  (In some cases, providing the actual values passed to the
    system call might be appropriate information for the detail message.)
   </para>

   <para>
    Rationale: Users don't know what all those functions do.
   </para>

  </simplesect>

  <simplesect>
   <title>Tricky words to avoid</title>

  <formalpara>
    <title>Unable</title>
   <para>
    <quote>Unable</quote> is nearly the passive voice.  Better use
    <quote>cannot</quote> or <quote>could not</quote>, as appropriate.
   </para>
  </formalpara>

  <formalpara>
    <title>Bad</title>
   <para>
    Error messages like <quote>bad result</quote> are really hard to interpret
    intelligently.  It's better to write why the result is <quote>bad</quote>,
    e.g., <quote>invalid format</quote>. 
   </para>
  </formalpara>

  <formalpara>
    <title>Illegal</title>
   <para>
    <quote>Illegal</quote> stands for a violation of the law, the rest is
    <quote>invalid</quote>. Better yet, say why it's invalid.
   </para>
  </formalpara>

  <formalpara>
    <title>Unknown</title>
   <para>
    Try to avoid <quote>unknown</quote>.  Consider <quote>error: unknown
    response</quote>.  If you don't know what the response is, how do you know
    it's erroneous? <quote>Unrecognized</quote> is often a better choice.
    Also, be sure to include the value being complained of. 
<programlisting>
BAD:    unknown node type
BETTER: unrecognized node type: 42
</programlisting>
   </para>
  </formalpara>

  <formalpara>
    <title>Find vs. Exists</title>
   <para>
    If the program uses a nontrivial algorithm to locate a resource (e.g., a
    path search) and that algorithm fails, it is fair to say that the program
    couldn't <quote>find</quote> the resource.  If, on the other hand, the
    expected location of the resource is known but the program cannot access
    it there then say that the resource doesn't <quote>exist</quote>.  Using
    <quote>find</quote> in this case sounds weak and confuses the issue. 
   </para>
  </formalpara>

  </simplesect>

  <simplesect>
   <title>Proper spelling</title>

   <para>
    Spell out words in full.  For instance, avoid:
  <itemizedlist>
   <listitem>
    <para>
     spec
    </para>
   </listitem>
   <listitem>
    <para>
     stats
    </para>
   </listitem>
   <listitem>
    <para>
     parens
    </para>
   </listitem>
   <listitem>
    <para>
     auth
    </para>
   </listitem>
   <listitem>
    <para>
     xact
    </para>
   </listitem>
  </itemizedlist>
   </para>

   <para>
    Rationale: This will improve consistency.
   </para>

  </simplesect>

  <simplesect>
   <title>Localization</title>

   <para>
    Keep in mind that error message texts need to be translated into other
    languages.  Follow the guidelines in <xref linkend="nls-guidelines">
    to avoid making life difficult for translators.
   </para>
  </simplesect>

  </sect1>

 </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->