coar 97/08/01 13:08:51
Modified: . styleguide.html
Log:
Update style guide with the majority results from the most
recent issue vote.
Revision Changes Path
1.4 +100 -46 apache-devsite/styleguide.html
Index: styleguide.html
===================================================================
RCS file: /export/home/cvs/apache-devsite/styleguide.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- styleguide.html 1997/07/16 10:15:48 1.3
+++ styleguide.html 1997/08/01 20:08:49 1.4
@@ -4,9 +4,11 @@
<H1>Apache Developers' C Language Style Guide</H1>
-<B>Compiled by Paul Sutton <A
-HREF="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</A></B>. Based on a vote
+<STRONG>Compiled by Paul Sutton <A
+HREF="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</A></STRONG>. Based on a
vote
taken in November, 1996.
+<BR>
+Further refinements voted upon in July 1997.
<HR>
@@ -24,42 +26,55 @@
<P><UL><code>-i4 -npsl -di0 -br -nce -d0 -cli0 -npcs -nfc1</code></UL>
<H2>The Guidelines</H2>
+ <UL>
+ <LI>Opening braces are given on the same lines as statements, or on the
+ following line at the start of a function definition.
+ </LI>
+ <LI>Code inside a block (whether surrounded by braces or not) is
+ indented by four space characters. Tab characters are not
+ used. Comments are indented to the same level as the surrounding
+ code.
+ </LI>
+ <LI>Closing braces are always on a separate line from surrounding
+ code, and are indented to line up with the start of the text on
+ the line containing the corresponding opening brace.
+ </LI>
+ <LI>Functions are declared with ANSI-style arguments.
+ </LI>
+ <LI>There is no space between the function name and the opening bracket
+ of the arguments to the function. There is a single space following
+ commas in argument lists and the semi-colons in for statements.
+ </LI>
+ <LI>Inside a <SAMP>switch()</SAMP> statement, the <SAMP>case</SAMP>
+ keywords are indented to the same level as the <SAMP>switch</SAMP> line.
+ </LI>
+ <LI>Operators in expressions should be surrounded by a single space
+ before and after, except for unary increment (++), decrement (--), and
+ negation (!) operators.
+ </LI>
+ <LI>There is no whitespace between a cast and the item modified
+ (<EM>e.g.</EM>, "<SAMP>(int)j</SAMP>" and not
+ "<SAMP>(int) j</SAMP>").
+ </LI>
+ <LI>If a cast is to a pointer type, there is a space between the type
+ and the <SAMP>*</SAMP> character (<EM>e.g.</EM>,
+ "<SAMP>(char *)i</SAMP>" instead of
+ "<SAMP>(char*)i</SAMP>")
+ </LI>
+ </UL>
-<P>Opening braces are given on the same lines as statements, or on the
- following line at the start of a function definition.
-
-<P>Code inside a block (whether surrounded by braces or not) is
- indented by four space characters. Tab characters are not
- used. Comments are indented to the same level as the surrounding
- code.
-
-<P>Closing braces are always on a separate line from surrounding
- code, and are indented to line up with the start of the text on
- the line containing the corresponding opening brace.
-
-<P>Functions are declared with ANSI-style arguments.
-
-<P>Inside a switch() statement, the "case" keywords are indented to
- the same level as the "switch" line.
-
-<P>There is no space between the function name and the opening bracket
- of the arguments to the function. There is a single space following
- commas in argument lists and the semi-colons in for statements.
-
-<P>Operators in expressions should be surrounded by a single space
- before and after, except for increment and decrement operators.
<H2>Details and Examples</H2>
<OL>
-<LI>Indentation, General Style
+<LI><STRONG>Indentation, General Style</STRONG>
<P>Each level of indentation of code is four spaces. Tab characters
should never be used. Specific indentation rules for function
declarations and control-flow keywords are given below.
<P>Example:
-<pre>
+<PRE>
main(int argc, char **argc)
{
if (argc != 0) {
@@ -68,8 +83,31 @@
}
exit(0);
}
-</pre>
-<LI>Comments
+</PRE>
+<P>
+<A NAME="long-exps">If an expression</A> (or a routine declaration or
+invocation) would extend
+past column 80, the terms or arguments are wrapped at a convenient spot
+and the wrapped portion is indented under the first term in the expression
+(or the first argument to the function).
+Conditional expressions should be wrapped to keep single or
+parenthesized terms as atomic as possible, and place Boolean operators
+at either the start (preferable) or end of the line.
+</P>
+<P>
+Example:
+</P>
+<PRE>
+ static const char *really_long_name(int i, int j,
+ const char *args, void *foo,
+ int k)
+
+ if (cond1 && (item2 || item3) && (!item4)
+ && (item5 || item6) && item7) {
+ do_a_thing();
+ }
+</PRE>
+<LI><STRONG>Comments</STRONG>
<P>Provide comments which explain the function of code where it is not
clear from the code itself. Provide rationale where necessary for
@@ -85,7 +123,7 @@
code;
</PRE>
-<LI>Function Declaration and Layout
+<LI><STRONG>Function Declaration and Layout</STRONG>
<P>Functions are laid out as follows:
@@ -97,24 +135,31 @@
</PRE>
<P>The return type is placed on the same line as the function. Arguments
- (if any) are given in ANSI style. If no arguments, use void. No space
+ (if any) are given in ANSI style. If no arguments, declare function
+ as <SAMP>void</SAMP>. No space
between function name and opening bracket, single space after comma
separating each argument. The opening brace is placed on the line
after the definition, indented to line up with the start of the
return type text. The code is indented with four spaces, and the closing
- brace is indented to line up with the opening brace.
+ brace is indented to line up with the opening brace. <STRONG>Also
+ see the section on indenting <A HREF="#long-exps">long declarations
+ and invocations</A>.</STRONG>
<P>
-<LI>Function Calls
+<LI><STRONG>Function Calls</STRONG>
<P>Space after commas in function calls. No space between function name
and opening bracket.
<PRE>
f(a, b);
</PRE>
+<P><STRONG>Also
+ see the section on indenting <A HREF="#long-exps">long declarations
+ and invocations</A>.</STRONG>
+</P>
+<LI><STRONG>Flow-Control Layout</STRONG>
-<LI>Flow-Control Layout
-
-<P>Flow-control (if, while, for, etc) are laid out as in this example:
+<P>Flow-control statements (<SAMP>if</SAMP>, <SAMP>while</SAMP>,
+ <SAMP>for</SAMP>, <EM>etc.</EM>) are laid out as in this example:
<PRE>
if (expr) {
@@ -128,13 +173,16 @@
<P>There is a space between the keyword and the opening bracket.
Opening brace placed on same line as the flow keyword. The code
itself is indented by four spaces. The closing brace is indented to
- line up with the opening brace. If an "else" clause is used, the
- else keyword is placed on the line following the closing brace and
- is indented to line up with the corresponding if.
+ line up with the opening brace. If an <SAMP>else</SAMP> clause is used,
the
+ <SAMP>else</SAMP> keyword is placed on the line following the closing
+ brace and is indented to line up with the corresponding
+ <SAMP>if</SAMP>. <STRONG>Also
+ see the section on indenting <A HREF="#long-exps">long
+ expressions</A>.</STRONG>
<P>
-<LI>For Layout
+<LI><STRONG><SAMP>for</SAMP> Layout</STRONG>
<P>Space after the semi-colons. Example:
@@ -142,9 +190,10 @@
for (a; b; c)
</PRE>
-<LI>Switch Layout
+<LI><STRONG><SAMP>switch</SAMP> Layout</STRONG>
-<P>"case" lines within a switch() indented to same level as the switch
+<P><SAMP>case</SAMP> lines within a <SAMP>switch()</SAMP> are indented to
+ same level as the switch
statement itself. The code for each case is indented by four spaces.
Braces are laid out as for other control-flow keywords. Example:
@@ -157,19 +206,24 @@
}
</PRE>
-<LI> Expressions
+<LI><STRONG>Expressions</STRONG>
<P>Space before and after assignment and other and operators. No space
- between increment or decrement operators and the lvalue. Examples:
+ between unary operators (increment, decrement, and negation) and the
+ lvalue. Examples:
<PRE>
a = b
a + b
- a < b
+ a < b
+ a = -b
+ a = !b
++a
</PRE>
-<LI>Capitalisation of Enums
+<LI><STRONG>Capitalisation of Enums</STRONG>
<P>No rule.
</OL>
+</BODY>
+</HTML>
