diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/src/sgml/sources.sgml | 1035 |
1 files changed, 1035 insertions, 0 deletions
diff --git a/doc/src/sgml/sources.sgml b/doc/src/sgml/sources.sgml new file mode 100644 index 0000000..0db36ae --- /dev/null +++ b/doc/src/sgml/sources.sgml @@ -0,0 +1,1035 @@ +<!-- doc/src/sgml/sources.sgml --> + + <chapter id="source"> + <title>PostgreSQL Coding Conventions</title> + + <sect1 id="source-format"> + <title>Formatting</title> + + <para> + Source code formatting uses 4 column tab spacing, with + tabs preserved (i.e., tabs are not expanded to spaces). + Each logical indentation level is one additional tab stop. + </para> + + <para> + Layout rules (brace positioning, etc.) follow BSD conventions. In + particular, curly braces for the controlled blocks of <literal>if</literal>, + <literal>while</literal>, <literal>switch</literal>, etc. go on their own lines. + </para> + + <para> + Limit line lengths so that the code is readable in an 80-column window. + (This doesn't mean that you must never go past 80 columns. For instance, + breaking a long error message string in arbitrary places just to keep the + code within 80 columns is probably not a net gain in readability.) + </para> + + <para> + To maintain a consistent coding style, do not use C++ style comments + (<literal>//</literal> comments). <application>pgindent</application> + will replace them with <literal>/* ... */</literal>. + </para> + + <para> + The preferred style for multi-line comment blocks is +<programlisting> +/* + * comment text begins here + * and continues here + */ +</programlisting> + Note that comment blocks that begin in column 1 will be preserved as-is + by <application>pgindent</application>, but it will re-flow indented comment blocks + as though they were plain text. If you want to preserve the line breaks + in an indented block, add dashes like this: +<programlisting> + /*---------- + * comment text begins here + * and continues here + *---------- + */ +</programlisting> + </para> + + <para> + While submitted patches do not absolutely have to follow these formatting + rules, it's a good idea to do so. Your code will get run through + <application>pgindent</application> before the next release, so there's no point in + making it look nice under some other set of formatting conventions. + A good rule of thumb for patches is <quote>make the new code look like + the existing code around it</quote>. + </para> + + <para> + The <filename>src/tools/editors</filename> directory contains sample settings + files that can be used with the <productname>Emacs</productname>, + <productname>xemacs</productname> or <productname>vim</productname> + editors to help ensure that they format code according to these + conventions. + </para> + + <para> + If you'd like to run <application>pgindent</application> locally + to help make your code match project style, see + the <filename>src/tools/pgindent</filename> directory. + </para> + + <para> + The text browsing tools <application>more</application> and + <application>less</application> can be invoked as: +<programlisting> +more -x4 +less -x4 +</programlisting> + to make them show tabs appropriately. + </para> + </sect1> + + <sect1 id="error-message-reporting"> + <title>Reporting Errors Within the Server</title> + + <indexterm> + <primary>ereport</primary> + </indexterm> + <indexterm> + <primary>elog</primary> + </indexterm> + + <para> + Error, warning, and log messages generated within the server code + should be created using <function>ereport</function>, or its older cousin + <function>elog</function>. The use of this function is complex enough to + require some explanation. + </para> + + <para> + There are two required elements for every message: a severity level + (ranging from <literal>DEBUG</literal> to <literal>PANIC</literal>) and a primary + message text. In addition there are optional elements, the most + common of which is an error identifier code that follows the SQL spec's + SQLSTATE conventions. + <function>ereport</function> itself is just a shell macro that exists + mainly for the syntactic convenience of making message generation + look like a single function call in the C source code. The only parameter + accepted directly by <function>ereport</function> is the severity level. + The primary message text and any optional message elements are + generated by calling auxiliary functions, such as <function>errmsg</function>, + within the <function>ereport</function> call. + </para> + + <para> + A typical call to <function>ereport</function> might look like this: +<programlisting> +ereport(ERROR, + errcode(ERRCODE_DIVISION_BY_ZERO), + errmsg("division by zero")); +</programlisting> + This specifies error severity level <literal>ERROR</literal> (a run-of-the-mill + error). The <function>errcode</function> call specifies the SQLSTATE error code + using a macro defined in <filename>src/include/utils/errcodes.h</filename>. The + <function>errmsg</function> call provides the primary message text. + </para> + + <para> + You will also frequently see this older style, with an extra set of + parentheses surrounding the auxiliary function calls: +<programlisting> +ereport(ERROR, + (errcode(ERRCODE_DIVISION_BY_ZERO), + errmsg("division by zero"))); +</programlisting> + The extra parentheses were required + before <productname>PostgreSQL</productname> version 12, but are now + optional. + </para> + + <para> + Here is a more complex example: +<programlisting> +ereport(ERROR, + errcode(ERRCODE_AMBIGUOUS_FUNCTION), + errmsg("function %s is not unique", + func_signature_string(funcname, nargs, + NIL, actual_arg_types)), + errhint("Unable to choose a best candidate function. " + "You might need to add explicit typecasts.")); +</programlisting> + This illustrates the use of format codes to embed run-time values into + a message text. Also, an optional <quote>hint</quote> message is provided. + The auxiliary function calls can be written in any order, but + conventionally <function>errcode</function> + and <function>errmsg</function> appear first. + </para> + + <para> + If the severity level is <literal>ERROR</literal> or higher, + <function>ereport</function> aborts execution of the current query + and does not return to the caller. If the severity level is + lower than <literal>ERROR</literal>, <function>ereport</function> returns normally. + </para> + + <para> + The available auxiliary routines for <function>ereport</function> are: + <itemizedlist> + <listitem> + <para> + <function>errcode(sqlerrcode)</function> specifies the SQLSTATE error identifier + code for the condition. If this routine is not called, the error + identifier defaults to + <literal>ERRCODE_INTERNAL_ERROR</literal> when the error severity level is + <literal>ERROR</literal> or higher, <literal>ERRCODE_WARNING</literal> when the + error level is <literal>WARNING</literal>, otherwise (for <literal>NOTICE</literal> + and below) <literal>ERRCODE_SUCCESSFUL_COMPLETION</literal>. + While these defaults are often convenient, always think whether they + are appropriate before omitting the <function>errcode()</function> call. + </para> + </listitem> + <listitem> + <para> + <function>errmsg(const char *msg, ...)</function> specifies the primary error + message text, and possibly run-time values to insert into it. Insertions + are specified by <function>sprintf</function>-style format codes. In addition to + the standard format codes accepted by <function>sprintf</function>, the format + code <literal>%m</literal> can be used to insert the error message returned + by <function>strerror</function> for the current value of <literal>errno</literal>. + <footnote> + <para> + That is, the value that was current when the <function>ereport</function> call + was reached; changes of <literal>errno</literal> within the auxiliary reporting + routines will not affect it. That would not be true if you were to + write <literal>strerror(errno)</literal> explicitly in <function>errmsg</function>'s + parameter list; accordingly, do not do so. + </para> + </footnote> + <literal>%m</literal> does not require any + corresponding entry in the parameter list for <function>errmsg</function>. + Note that the message string will be run through <function>gettext</function> + for possible localization before format codes are processed. + </para> + </listitem> + <listitem> + <para> + <function>errmsg_internal(const char *msg, ...)</function> is the same as + <function>errmsg</function>, except that the message string will not be + translated nor included in the internationalization message dictionary. + This should be used for <quote>cannot happen</quote> cases that are probably + not worth expending translation effort on. + </para> + </listitem> + <listitem> + <para> + <function>errmsg_plural(const char *fmt_singular, const char *fmt_plural, + unsigned long n, ...)</function> is like <function>errmsg</function>, but with + support for various plural forms of the message. + <replaceable>fmt_singular</replaceable> is the English singular format, + <replaceable>fmt_plural</replaceable> is the English plural format, + <replaceable>n</replaceable> is the integer value that determines which plural + form is needed, and the remaining arguments are formatted according + to the selected format string. For more information see + <xref linkend="nls-guidelines"/>. + </para> + </listitem> + <listitem> + <para> + <function>errdetail(const char *msg, ...)</function> supplies an optional + <quote>detail</quote> message; this is to be used when there is additional + information that seems inappropriate to put in the primary message. + The message string is processed in just the same way as for + <function>errmsg</function>. + </para> + </listitem> + <listitem> + <para> + <function>errdetail_internal(const char *msg, ...)</function> is the same + as <function>errdetail</function>, except that the message string will not be + translated nor included in the internationalization message dictionary. + This should be used for detail messages that are not worth expending + translation effort on, for instance because they are too technical to be + useful to most users. + </para> + </listitem> + <listitem> + <para> + <function>errdetail_plural(const char *fmt_singular, const char *fmt_plural, + unsigned long n, ...)</function> is like <function>errdetail</function>, but with + support for various plural forms of the message. + For more information see <xref linkend="nls-guidelines"/>. + </para> + </listitem> + <listitem> + <para> + <function>errdetail_log(const char *msg, ...)</function> is the same as + <function>errdetail</function> except that this string goes only to the server + log, never to the client. If both <function>errdetail</function> (or one of + its equivalents above) and + <function>errdetail_log</function> are used then one string goes to the client + and the other to the log. This is useful for error details that are + too security-sensitive or too bulky to include in the report + sent to the client. + </para> + </listitem> + <listitem> + <para> + <function>errdetail_log_plural(const char *fmt_singular, const char + *fmt_plural, unsigned long n, ...)</function> is like + <function>errdetail_log</function>, but with support for various plural forms of + the message. + For more information see <xref linkend="nls-guidelines"/>. + </para> + </listitem> + <listitem> + <para> + <function>errhint(const char *msg, ...)</function> supplies an optional + <quote>hint</quote> message; this is to be used when offering suggestions + about how to fix the problem, as opposed to factual details about + what went wrong. + The message string is processed in just the same way as for + <function>errmsg</function>. + </para> + </listitem> + <listitem> + <para> + <function>errhint_plural(const char *fmt_singular, const char *fmt_plural, + unsigned long n, ...)</function> is like <function>errhint</function>, but with + support for various plural forms of the message. + For more information see <xref linkend="nls-guidelines"/>. + </para> + </listitem> + <listitem> + <para> + <function>errcontext(const char *msg, ...)</function> is not normally called + directly from an <function>ereport</function> message site; rather it is used + in <literal>error_context_stack</literal> callback functions to provide + information about the context in which an error occurred, such as the + current location in a PL function. + The message string is processed in just the same way as for + <function>errmsg</function>. Unlike the other auxiliary functions, this can + be called more than once per <function>ereport</function> call; the successive + strings thus supplied are concatenated with separating newlines. + </para> + </listitem> + <listitem> + <para> + <function>errposition(int cursorpos)</function> specifies the textual location + of an error within a query string. Currently it is only useful for + errors detected in the lexical and syntactic analysis phases of + query processing. + </para> + </listitem> + <listitem> + <para> + <function>errtable(Relation rel)</function> specifies a relation whose + name and schema name should be included as auxiliary fields in the error + report. + </para> + </listitem> + <listitem> + <para> + <function>errtablecol(Relation rel, int attnum)</function> specifies + a column whose name, table name, and schema name should be included as + auxiliary fields in the error report. + </para> + </listitem> + <listitem> + <para> + <function>errtableconstraint(Relation rel, const char *conname)</function> + specifies a table constraint whose name, table name, and schema name + should be included as auxiliary fields in the error report. Indexes + should be considered to be constraints for this purpose, whether or + not they have an associated <structname>pg_constraint</structname> entry. Be + careful to pass the underlying heap relation, not the index itself, as + <literal>rel</literal>. + </para> + </listitem> + <listitem> + <para> + <function>errdatatype(Oid datatypeOid)</function> specifies a data + type whose name and schema name should be included as auxiliary fields + in the error report. + </para> + </listitem> + <listitem> + <para> + <function>errdomainconstraint(Oid datatypeOid, const char *conname)</function> + specifies a domain constraint whose name, domain name, and schema name + should be included as auxiliary fields in the error report. + </para> + </listitem> + <listitem> + <para> + <function>errcode_for_file_access()</function> is a convenience function that + selects an appropriate SQLSTATE error identifier for a failure in a + file-access-related system call. It uses the saved + <literal>errno</literal> to determine which error code to generate. + Usually this should be used in combination with <literal>%m</literal> in the + primary error message text. + </para> + </listitem> + <listitem> + <para> + <function>errcode_for_socket_access()</function> is a convenience function that + selects an appropriate SQLSTATE error identifier for a failure in a + socket-related system call. + </para> + </listitem> + <listitem> + <para> + <function>errhidestmt(bool hide_stmt)</function> can be called to specify + suppression of the <literal>STATEMENT:</literal> portion of a message in the + postmaster log. Generally this is appropriate if the message text + includes the current statement already. + </para> + </listitem> + <listitem> + <para> + <function>errhidecontext(bool hide_ctx)</function> can be called to + specify suppression of the <literal>CONTEXT:</literal> portion of a message in + the postmaster log. This should only be used for verbose debugging + messages where the repeated inclusion of context would bloat the log + too much. + </para> + </listitem> + </itemizedlist> + </para> + + <note> + <para> + At most one of the functions <function>errtable</function>, + <function>errtablecol</function>, <function>errtableconstraint</function>, + <function>errdatatype</function>, or <function>errdomainconstraint</function> should + be used in an <function>ereport</function> call. These functions exist to + allow applications to extract the name of a database object associated + with the error condition without having to examine the + potentially-localized error message text. + These functions should be used in error reports for which it's likely + that applications would wish to have automatic error handling. As of + <productname>PostgreSQL</productname> 9.3, complete coverage exists only for + errors in SQLSTATE class 23 (integrity constraint violation), but this + is likely to be expanded in future. + </para> + </note> + + <para> + There is an older function <function>elog</function> that is still heavily used. + An <function>elog</function> call: +<programlisting> +elog(level, "format string", ...); +</programlisting> + is exactly equivalent to: +<programlisting> +ereport(level, errmsg_internal("format string", ...)); +</programlisting> + Notice that the SQLSTATE error code is always defaulted, and the message + string is not subject to translation. + Therefore, <function>elog</function> should be used only for internal errors and + low-level debug logging. Any message that is likely to be of interest to + ordinary users should go through <function>ereport</function>. Nonetheless, + there are enough internal <quote>cannot happen</quote> error checks in the + system that <function>elog</function> is still widely used; it is preferred for + those messages for its notational simplicity. + </para> + + <para> + Advice about writing good error messages can be found in + <xref linkend="error-style-guide"/>. + </para> + </sect1> + + <sect1 id="error-style-guide"> + <title>Error Message Style Guide</title> + + <para> + This style guide is offered in the hope of maintaining a consistent, + user-friendly style throughout all the messages generated by + <productname>PostgreSQL</productname>. + </para> + + <simplesect id="error-style-guide-what-goes-where"> + <title>What Goes Where</title> + + <para> + The primary message should be short, factual, and avoid reference to + implementation details such as specific function names. + <quote>Short</quote> means <quote>should fit on one line under normal + conditions</quote>. Use a detail message if needed to keep the primary + message short, or if you feel a need to mention implementation details + such as the particular system call that failed. Both primary and detail + messages should be factual. Use a hint message for suggestions about what + to do to fix the problem, especially if the suggestion might not always be + applicable. + </para> + + <para> + For example, instead of: +<programlisting> +IpcMemoryCreate: shmget(key=%d, size=%u, 0%o) failed: %m +(plus a long addendum that is basically a hint) +</programlisting> + write: +<programlisting> +Primary: could not create shared memory segment: %m +Detail: Failed syscall was shmget(key=%d, size=%u, 0%o). +Hint: the addendum +</programlisting> + </para> + + <para> + Rationale: keeping the primary message short helps keep it to the point, + and lets clients lay out screen space on the assumption that one line is + enough for error messages. Detail and hint messages can be relegated to a + verbose mode, or perhaps a pop-up error-details window. Also, details and + hints would normally be suppressed from the server log to save + space. Reference to implementation details is best avoided since users + aren't expected to know the details. + </para> + + </simplesect> + + <simplesect id="error-style-guide-formatting"> + <title>Formatting</title> + + <para> + Don't put any specific assumptions about formatting into the message + texts. Expect clients and the server log to wrap lines to fit their own + needs. In long messages, newline characters (\n) can be used to indicate + suggested paragraph breaks. Don't end a message with a newline. Don't + use tabs or other formatting characters. (In error context displays, + newlines are automatically added to separate levels of context such as + function calls.) + </para> + + <para> + Rationale: Messages are not necessarily displayed on terminal-type + displays. In GUI displays or browsers these formatting instructions are + at best ignored. + </para> + + </simplesect> + + <simplesect id="error-style-guide-quotation-marks"> + <title>Quotation Marks</title> + + <para> + English text should use double quotes when quoting is appropriate. + Text in other languages should consistently use one kind of quotes that is + consistent with publishing customs and computer output of other programs. + </para> + + <para> + Rationale: The choice of double quotes over single quotes is somewhat + arbitrary, but tends to be the preferred use. Some have suggested + choosing the kind of quotes depending on the type of object according to + SQL conventions (namely, strings single quoted, identifiers double + quoted). But this is a language-internal technical issue that many users + 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 id="error-style-guide-quotes"> + <title>Use of Quotes</title> + + <para> + Always use quotes 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 + as needed (for example, <function>format_type_be()</function>). 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 id="error-style-guide-grammar-punctuation"> + <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. Put two spaces after + the period if another sentence follows (for English text; might be + inappropriate in other languages). + </para> + + <para> + Error context strings: Do not capitalize the first letter and do + not end the string with a period. Context strings should normally + not be complete 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 might need to include multiple sentences. For consistency, they should + follow complete-sentence style even when there's only one sentence. + </para> + + </simplesect> + + <simplesect id="error-style-guide-case"> + <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 id="error-style-guide-passive-voice"> + <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 id="error-style-guide-tense"> + <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 might + exist. + </para> + + <para> + The second form indicates that 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 id="error-style-guide-object-type"> + <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</quote> + refers to. + </para> + + </simplesect> + + <simplesect id="error-style-guide-brackets"> + <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 id="error-style-guide-error-messages"> + <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 id="error-style-guide-error-reasons"> + <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 id="error-style-guide-function-names"> + <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_strtoint32: error in "z": cannot parse "z" +BETTER: invalid input syntax for type 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 id="error-style-guide-tricky-words"> + <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> + + <formalpara> + <title>May vs. Can vs. Might</title> + <para> + <quote>May</quote> suggests permission (e.g., "You may borrow my rake."), + and has little use in documentation or error messages. + <quote>Can</quote> suggests ability (e.g., "I can lift that log."), + and <quote>might</quote> suggests possibility (e.g., "It might rain + today."). Using the proper word clarifies meaning and assists + translation. + </para> + </formalpara> + + <formalpara> + <title>Contractions</title> + <para> + Avoid contractions, like <quote>can't</quote>; use + <quote>cannot</quote> instead. + </para> + </formalpara> + + <formalpara> + <title>Non-negative</title> + <para> + Avoid <quote>non-negative</quote> as it is ambiguous + about whether it accepts zero. It's better to use + <quote>greater than zero</quote> or + <quote>greater than or equal to zero</quote>. + </para> + </formalpara> + + </simplesect> + + <simplesect id="error-style-guide-spelling"> + <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 id="error-style-guide-localization"> + <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> + + <sect1 id="source-conventions"> + <title>Miscellaneous Coding Conventions</title> + + <simplesect id="source-conventions-c-standard"> + <title>C Standard</title> + <para> + Code in <productname>PostgreSQL</productname> should only rely on language + features available in the C99 standard. That means a conforming + C99 compiler has to be able to compile postgres, at least aside + from a few platform dependent pieces. + </para> + <para> + A few features included in the C99 standard are, at this time, not + permitted to be used in core <productname>PostgreSQL</productname> + code. This currently includes variable length arrays, intermingled + declarations and code, <literal>//</literal> comments, universal + character names. Reasons for that include portability and historical + practices. + </para> + <para> + Features from later revisions of the C standard or compiler specific + features can be used, if a fallback is provided. + </para> + <para> + For example <literal>_Static_assert()</literal> and + <literal>__builtin_constant_p</literal> are currently used, even though + they are from newer revisions of the C standard and a + <productname>GCC</productname> extension respectively. If not available + we respectively fall back to using a C99 compatible replacement that + performs the same checks, but emits rather cryptic messages and do not + use <literal>__builtin_constant_p</literal>. + </para> + </simplesect> + + <simplesect id="source-conventions-macros-inline"> + <title>Function-Like Macros and Inline Functions</title> + <para> + Both macros with arguments and <literal>static inline</literal> + functions may be used. The latter are preferable if there are + multiple-evaluation hazards when written as a macro, as e.g., the + case with +<programlisting> +#define Max(x, y) ((x) > (y) ? (x) : (y)) +</programlisting> + or when the macro would be very long. In other cases it's only + possible to use macros, or at least easier. For example because + expressions of various types need to be passed to the macro. + </para> + <para> + When the definition of an inline function references symbols + (i.e., variables, functions) that are only available as part of the + backend, the function may not be visible when included from frontend + code. +<programlisting> +#ifndef FRONTEND +static inline MemoryContext +MemoryContextSwitchTo(MemoryContext context) +{ + MemoryContext old = CurrentMemoryContext; + + CurrentMemoryContext = context; + return old; +} +#endif /* FRONTEND */ +</programlisting> + In this example <literal>CurrentMemoryContext</literal>, which is only + available in the backend, is referenced and the function thus + hidden with a <literal>#ifndef FRONTEND</literal>. This rule + exists because some compilers emit references to symbols + contained in inline functions even if the function is not used. + </para> + </simplesect> + + <simplesect id="source-conventions-signal-handlers"> + <title>Writing Signal Handlers</title> + <para> + To be suitable to run inside a signal handler code has to be + written very carefully. The fundamental problem is that, unless + blocked, a signal handler can interrupt code at any time. If code + inside the signal handler uses the same state as code outside + chaos may ensue. As an example consider what happens if a signal + handler tries to acquire a lock that's already held in the + interrupted code. + </para> + <para> + Barring special arrangements code in signal handlers may only + call async-signal safe functions (as defined in POSIX) and access + variables of type <literal>volatile sig_atomic_t</literal>. A few + functions in <command>postgres</command> are also deemed signal safe, importantly + <function>SetLatch()</function>. + </para> + <para> + In most cases signal handlers should do nothing more than note + that a signal has arrived, and wake up code running outside of + the handler using a latch. An example of such a handler is the + following: +<programlisting> +static void +handle_sighup(SIGNAL_ARGS) +{ + int save_errno = errno; + + got_SIGHUP = true; + SetLatch(MyLatch); + + errno = save_errno; +} +</programlisting> + <varname>errno</varname> is saved and restored because + <function>SetLatch()</function> might change it. If that were not done + interrupted code that's currently inspecting <varname>errno</varname> might see the wrong + value. + </para> + </simplesect> + + <simplesect id="source-conventions-function-pointers"> + <title>Calling Function Pointers</title> + + <para> + For clarity, it is preferred to explicitly dereference a function pointer + when calling the pointed-to function if the pointer is a simple variable, + for example: +<programlisting> +(*emit_log_hook) (edata); +</programlisting> + (even though <literal>emit_log_hook(edata)</literal> would also work). + When the function pointer is part of a structure, then the extra + punctuation can and usually should be omitted, for example: +<programlisting> +paramInfo->paramFetch(paramInfo, paramId); +</programlisting> + </para> + </simplesect> + </sect1> + </chapter> |