c-style.htm

GhostScript的源代码

<p>
(using the comment convention appropriate to the language of the file), and

<li>a summary, no more than one line, of what the file contains.
</ol>

<p>
If you create a file by copying the beginning of another file, be sure to
update the copyright year and change the file name.

<h2><a name="Makefiles"></a>Makefiles</h2>

<p>
For each

<blockquote><b><tt>
#include "xxx.h"
</tt></b></blockquote>

<p>
make sure there is a dependency on <b><tt>$(xxx_h)</tt></b> in the
makefile.  If xxx ends with a "<b><tt>_</tt></b>", this rule still holds,
so that if you code

<blockquote><b><tt>
#include "math_.h"
</tt></b></blockquote>

<p>
the makefile must contain a dependency on "<b><tt>$(math__h)</tt></b>"
(note the two underscores "<b><tt>__</tt></b>").

<p>
List the dependencies bottom-to-top, like the <b><tt>#include</tt></b>
statements themselves; within each level, list them alphabetically.  Do
this also with <b><tt>#include</tt></b> statements themselves whenever
possible (but sometimes there are inter-header dependencies that require
bending this rule).

<h2><a name="C_code_generally"></a>C code in general</h2>

<p>
List <b><tt>#include</tt></b> statements from "bottom" to "top", that is,
in the following order:

<blockquote><ol>
<li>System includes (<b><tt>"xxx_.h"</tt></b>)
<li><b><tt>gs*.h</tt></b>
<li><b><tt>gx*.h</tt></b> (yes, <b><tt>gs</tt></b> and <b><tt>gx</tt></b>
are in the wrong order.)
<li><b><tt>s*.h</tt></b>
<li><b><tt>i*.h</tt></b> (or other interpreter headers that don't start
with "<b><tt>i</tt></b>")
</ol></blockquote>

<h3><a name="Headers"></a>Headers (<b><tt>.h</tt></b> files)</h3>

<p>
In header files, always use the following at the beginning of a header file
to prevent double inclusion:

<blockquote>
{{ Copyright notice etc. }}<br><br>

<b><tt>#ifndef </tt></b>&lt;filename&gt;<b><tt>_INCLUDED</tt></b><br>
<b><tt>#define </tt></b>&lt;filename&gt;<b><tt>_INCLUDED</tt></b><br><br>

{{ The contents of the file }}<br><br>

<b><tt>#endif /* </tt></b>&lt;filename&gt;<b><tt>_INCLUDED */</tt></b>
</blockquote>

<p>
The header file is the first place that a reader goes for
information about procedures, structures, constants, etc., so ensure that
every procedure and structure has a comment that says what it does.  Divide
procedures into meaningful groups set off by some distinguished form of
comment.

<h3><a name="Executable_code"></a>Executable code (<b><tt>.c</tt></b> files)</h3>

<p>
After the initial comments, arrange C files in the following order:

<blockquote><ol>
<li><b><tt>#include</tt></b> statements
<li>Exported data declarations
<li>Explicit externs (if necessary)
<li>Forward declarations of procedures
<li>Private data declarations
<li>Exported procedures
<li>Private procedures
</ol></blockquote>

<p>
Be flexible about the order of the declarations if necessary to improve
readability.  Many older files don't follow this order, often without good
reason.

<hr>

<h1><a name="Formatting"></a>Formatting</h1>

<h2><a name="Indentation"></a>Indentation</h2>

<p>
We've formatted all of our code using the GNU <b><tt>indent</tt></b> program.

<blockquote><b><tt>
indent&nbsp;-bad&nbsp;-nbap&nbsp;-nsob&nbsp;-br&nbsp;-ce&nbsp;-cli4&nbsp;-npcs&nbsp;-ncs&nbsp;\<br>
&nbsp;&nbsp;&nbsp;-i4&nbsp;-di0&nbsp;-psl&nbsp;-lp&nbsp;-lps&nbsp;somefile.c
</tt></b></blockquote>

<p>
does a 98% accurate job of producing our preferred style.  Unfortunately,
there are bugs in all versions of GNU <b><tt>indent</tt></b>, requiring
both pre- and post-processing of the code.  The <b><tt>gsindent</tt></b>
script in the Ghostscript fileset contains the necessary workarounds.

<p>
Put indentation points every 4 spaces, with 8 spaces = 1 tab stop.

<p>
Indent in-line blocks thus:

<blockquote>
<b><tt>{</tt></b><br>
&nbsp;&nbsp;&nbsp;... declarations ...<br>
&nbsp;&nbsp;&nbsp;{{ blank line if any declarations above }}<br>
&nbsp;&nbsp;&nbsp;... statements ...<br>
<b><tt>}</tt></b>
</blockquote>

<p>
Similarly, indent procedures thus:

<blockquote>
return_type<br>
proc_name(... arguments ...)<br>
<b><tt>{</tt></b><br>
&nbsp;&nbsp;&nbsp;... declarations ...<br>
&nbsp;&nbsp;&nbsp;{{ blank line if any declarations above }}<br>
&nbsp;&nbsp;&nbsp;... statements ...<br>
<b><tt>}</tt></b>
</blockquote>

<p>
If a control construct (<b><tt>if</tt></b>, <b><tt>do</tt></b>,
<b><tt>while</tt></b>, or <b><tt>for</tt></b>) has a one-line body, use
this:

<blockquote>
... control construct ...<br>
&nbsp;&nbsp;&nbsp;... subordinate simple statement ...
</blockquote>

<p>
If it has a multi-line body, use this:

<blockquote>
... control construct ... <b><tt>{</tt></b><br>
&nbsp;&nbsp;&nbsp;... subordinate code ...
<b><tt>}</tt></b>
</blockquote>

<p>
If the subordinate code has declarations, see blocks above.

<p>
For if-else statements, do this:

<blockquote>
<b><tt>if (</tt></b> ...<b><tt> ) {</tt></b><br>
&nbsp;&nbsp;&nbsp;... subordinate code ...<br>
<b><tt>} else if (</tt></b> ...<b><tt> ) {</tt></b><br>
&nbsp;&nbsp;&nbsp;... subordinate code ...<br>
<b><tt>} else {</tt></b><br>
&nbsp;&nbsp;&nbsp;... subordinate code ...<br>
<b><tt>}</tt></b>
</blockquote>

<p>
Similarly, for do-while statements, do this:

<blockquote>
<b><tt>do {</tt></b><br>
&nbsp;&nbsp;&nbsp;... body ...<br>
<b><tt>} while (</tt></b> ... condition ... <b><tt>);</tt></b>
</blockquote>

<h2><a name="Spaces"></a>Spaces</h2>

<p>
Do put a space:
<ul>
<li>after every comma and semicolon, unless it ends a line;
<li>around every binary operator, although you can omit the spaces around
the innermost operator in a nested expression if you like;
<li>on both sides of the parentheses of an if, for, or while.
</ul>

<p>
Don't put a space:
<ul>
<li>at the end of a line;
<li>before a comma or semicolon;
<li>after unary prefix operators;
<li>before the parenthesis of a macro or procedure call.
</ul>

<h2><a name="Parentheses"></a>Parentheses</h2>

<p>
Parentheses are important in only a few places:

<ul>
<li>Around the inner subexpressions in expressions that mix
<b><tt>&amp;&amp;</tt></b> and <b><tt>||</tt></b>, even if they are not
required by precedence, for example

<blockquote><b><tt>
(xx &amp;&amp; yy) || zz
</tt></b></blockquote>

<li>Similarly around inner subexpressions in expressions that mix
<b><tt>&amp;</tt></b>, <b><tt>|</tt></b>, or shifts, especially if mixing
these with other operators, for instance

<blockquote><b><tt>
(x &lt;&lt; 3) | (y &gt;&gt; 5)
</tt></b></blockquote>

<li>In macro definitions around every use of an argument that logically
could be an expression, for example

<blockquote><b><tt>
((x) * (x) + (y) * (y))
</tt></b></blockquote>

</ul>

<p>
Anywhere else, given the choice, use fewer parentheses.

<p>
For stylistic consistency with the existing Ghostscript code, put
parentheses around conditional expressions even if they aren't
syntactically required, unless you really dislike doing this.  Note that
the parentheses should go around the entire expression, not the condition.
For instance, instead of

<blockquote><b><tt>
hpgl_add_point_to_path(pgls, arccoord_x, arccoord_y,<br>
&nbsp;&nbsp;&nbsp;(pgls-&gt;g.pen_down) ? gs_lineto : gs_moveto);
</tt></b></blockquote>

<p>
use

<blockquote><b><tt>
hpgl_add_point_to_path(pgls, arccoord_x, arccoord_y,<br>
&nbsp;&nbsp;&nbsp;(pgls-&gt;g.pen_down ? gs_lineto : gs_moveto));
</tt></b></blockquote>

<hr>

<h1><a name="Naming"></a>Naming</h1>

<h2><a name="General_naming"></a>General rules</h2>

<p>
Use fully spelled-out English words in names, rather than contractions.
This is most important for procedure and macro names, global variables and
constants, values of <b><tt>#define</tt></b> and <b><tt>enum</tt></b>,
<b><tt>structure</tt></b> and other <b><tt>typedef</tt></b> names, and
structure member names, and for argument and variable names which have
uninformative types like <b><tt>int</tt></b>.  It's not very important for
arguments or local variables of distinctive types, or for local index or
count variables.

<p>
Avoid names that run English words together:
"<b><tt>hpgl_compute_arc_center</tt></b>" is better than
"<b><tt>hpgl_compute_arccenter</tt></b>".  However, for terms drawn from
some predefined source, like the names of PostScript operators, use a term
in its well-known form (for instance, <b><tt>gs_setlinewidth</tt></b>
rather than <b><tt>gs_set_line_width</tt></b>).

<p>
Procedures, variables, and structures visible outside a single
<b><tt>.c</tt></b> file should generally have prefixes that indicate what
subsystem they belong to (in the case of Ghostscript, <b><tt>gs_</tt></b>
or <b><tt>gx_</tt></b>).  This rule isn't followed very consistently.

<h2><a name="Conventional_names"></a>Names used by convention</h2>

<p>
The Ghostscript code uses certain names consistently for certain kinds of
values.  Some of the commonest and least obvious are these two:

<h3><a name="code"></a><b><tt>code</tt></b></h3>

<blockquote>
A value to be returned from a procedure:

<p>
<table cellpadding=0 cellspacing=0>
<tr valign=top>	<td align=right>&lt; 0
	<td>&nbsp;&nbsp;&nbsp;&nbsp;
	<td>An error code defined in <b><tt>gserrors.h</tt></b> (or <b><tt>errors.h</tt></b>)
<tr valign=top>	<td align=right>0
	<td>&nbsp;
	<td>Normal return
<tr valign=top>	<td align=right>&gt; 0
	<td>&nbsp;
	<td>A non-standard but successful return (which must be documented, preferably with the procedure's prototype)
</table>

</blockquote>

<h3><a name="status"></a><b><tt>status</tt></b></h3>

<blockquote>
A value returned from a stream procedure:

<p>
<table cellpadding=0 cellspacing=0>
<tr valign=top>	<td align=right>&lt; 0
	<td>&nbsp;&nbsp;&nbsp;&nbsp;
	<td>An exceptional condition as defined in <b><tt>scommon.h</tt></b>
<tr valign=top>	<td align=right>0
	<td>&nbsp;
	<td>Normal return (or, from the "<b><tt>process</tt></b>" procedure, means that more input is needed)
<tr valign=top>	<td align=right>1
	<td>&nbsp;
	<td>More output space is needed (from the "<b><tt>process</tt></b>" procedure)
</table>
</blockquote>

<hr>

<h1><a name="Miscellany"></a>Miscellany</h1>

<h2><a name="Single_use_procedures"></a>Single-use procedures</h2>

<p>
In general, don't create procedures that are private and only called from
one place.  However, if a compound statement (especially an arm of a
conditional) is too long for the eye easily to match its enclosing braces
"<b><tt>{...}</tt></b>" -- that is, longer than 10 or 15 lines -- and it
doesn't use or set a lot of state held in outer local variables, it may be
more readable if you put it in a procedure.

<h2><a name="Local_variables"></a>Local variables</h2>

<p>
Don't assign new values to procedure parameters.  It makes debugging very
confusing when the parameter values printed for a procedure are not the
ones actually supplied by the caller.  Instead use a separate local
variable initialized to the value of the parameter.

<p>
If a local variable is only assigned a value once, assign it that value at
its declaration, if possible.  For example,

<blockquote>
<b><tt>int x = </tt></b>some expression <b><tt>;</tt></b>
</blockquote>

<p>
rather than

<blockquote>
<b><tt>int x;</tt></b><br>
...<br>
<b><tt>x = </tt></b> some expression <b><tt>;</tt></b>
</blockquote>

<p>
Use a local pointer variable like this to "narrow" pointer types:

<blockquote>
<b><tt>int</tt></b><br>
someproc(... <b><tt>gx_device *dev</tt></b> ...)<br>
<b><tt>{<br>
&nbsp;&nbsp;&nbsp;gx_device_printer *const pdev = (gx_device_printer *)dev;</tt></b><br>
&nbsp;&nbsp;&nbsp;...<br>
<b><tt>}</tt></b>
</blockquote>

<h2><a name="Error_handling"></a>Error-handling</h2>

<p>
Every caller should check for error returns and, in general, propagate them
to <b>its</b> callers.  By convention, nearly every procedure returns an
<b><tt>int</tt></b> to indicate the outcome of the call:

<blockquote><table cellpadding=0 cellspacing=0>
<tr valign=top>	<td align=right>&lt; 0
	<td>&nbsp;&nbsp;&nbsp;&nbsp;
	<td>Error return
<tr valign=top>	<td align=right>0
	<td>&nbsp;
	<td>Normal return
<tr valign=top>	<td align=right>&gt; 0
	<td>&nbsp;
	<td>Non-error return other than the normal case
</table></blockquote>

<!-- [2.0 end contents] ---------------------------------------------------- -->

<!-- [3.0 begin visible trailer] ------------------------------------------- -->
<hr>

<font size=2>

<p>Copyright &copy; 1996, 1997, 1998 Aladdin Enterprises.  All rights reserved.

<p>This file is part of Aladdin Ghostscript.  See the
<a href="Public.htm">Aladdin Free Public License</a> (the "License") for
full details of the terms of using, copying, modifying, and redistributing
Aladdin Ghostscript.

<p>
Ghostscript version 5.50, 16 September 1998

</font>

<!-- [3.0 end visible trailer] --------------------------------------------- -->

</body>
</html>