Coding style/Formatting - Revision history

Ghudson at 15:18, 19 October 2012

2012-10-19T15:18:42Z

TomYu: add NOTOC

2012-04-26T18:11:57Z

add __NOTOC__

Ghudson at 04:21, 17 April 2012

2012-04-17T04:21:40Z

TomYu: /* Comment formatting */ reflect actual doxygen markup practice

2010-11-17T23:04:51Z

‎Comment formatting: reflect actual doxygen markup practice

TomYu: new section on character encoding/repertoire

2010-10-12T19:35:15Z

new section on character encoding/repertoire

Ghudson: /* Comment formatting */

2009-12-02T23:50:01Z

‎Comment formatting

TomYu: /* No tab characters */ demo

2009-10-02T20:42:54Z

‎No tab characters: demo

TomYu: /* Four-column basic indentation offset */ clarify indent vs tab stop

2009-06-08T20:40:52Z

‎Four-column basic indentation offset: clarify indent vs tab stop

Ghudson: /* Function definitions and declarations */

2009-05-27T19:52:19Z

‎Function definitions and declarations

TomYu: /* No tab characters */

2008-12-17T21:03:20Z

‎No tab characters

@@ Line 10: / Line 10: @@
 * Put spaces after flow control keywords but not after function names or cast operators.
 * Put open braces on the same line as flow control statements, separate by a space.
 * Put spaces around binary operators, but not unary operators.
 * When breaking long lines, break after binary operators, not before.
@@ Line 287: / Line 289: @@
 == Flow control statements ==
 <pre>
 if (x) {
     foo(x);
+}
 </pre>
@@ Line 308: / Line 318: @@
 if (x) {
     foo();
 } else if (y) {
     bar();

← Older revision		Revision as of 18:11, 26 April 2012
Line 1:		Line 1:
		+	__NOTOC__
	The following coding style considerations apply to the most mechanical aspects of C source code style.		The following coding style considerations apply to the most mechanical aspects of C source code style.

← Older revision		Revision as of 04:21, 17 April 2012
Line 1:		Line 1:
	The following coding style considerations apply to the most mechanical aspects of C source code style.		The following coding style considerations apply to the most mechanical aspects of C source code style.
		+
		+	== Quick summary ==
		+
		+	* Keep lines to 79 characters or less.
		+	* Use four-column indents.
		+	* Do not use tabs (except in the few files where they're still in use).
		+	* For comments longer than two lines, put the /* and */ on their own lines.
		+	* Put spaces after flow control keywords but not after function names or cast operators.
		+	* Put open braces on the same line as flow control statements, separate by a space.
		+	* Put spaces around binary operators, but not unary operators.
		+	* When breaking long lines, break after binary operators, not before.
		+	* Don't parenthesize return statements.
		+	* Use UTF-8 for non-ASCII characters in comments (as in proper names).

	== Maximum width 79 columns ==		== Maximum width 79 columns ==

@@ Line 119: / Line 119: @@
 Since we are mostly aiming for C '89 compatibility, don't use "<code>//</code>" comments.
-For Doxygen markup in comment blocks, use "<code>!</code>" (exclamation point) to begin a Doxygen block, and "<code>\</code>" (backslash) for Doxygen command keywords.
+For Doxygen markup in comment blocks, use an extra asterisk "<code>*</code>" to begin a Doxygen block, and "<code>@</code>" (at-sign) for Doxygen command keywords.
 <pre>
-/*!
+/**
- * \file krb5.h
+ * @file krb5.h
- * \brief the main krb5 header
+ * @brief the main krb5 header
  */
 </pre>

← Older revision		Revision as of 19:35, 12 October 2010
Line 308:		Line 308:

	This style is mostly for consistency with the BSD coding style. The GNU brace style consumes a larger amount of vertical space. The "brace-else-if-brace" style also prevents "stairstepping" within a long series of conditional statements.		This style is mostly for consistency with the BSD coding style. The GNU brace style consumes a larger amount of vertical space. The "brace-else-if-brace" style also prevents "stairstepping" within a long series of conditional statements.
		+
		+	== UTF-8 character encoding/repertoire ==
		+
		+	The character encoding for source code should be UTF-8. The use of characters outside the US-ASCII repertoire should be restricted to spelling proper names in comments and similar things. Avoid characters such as "curly quotation marks" when ordinary US-ASCII equivalents exist.
		+
		+	=== Current conformance ===
		+
		+	Current code mostly conforms. Limiting the use of non-ASCII characters enhances portability, and there are very few reasons for non-ASCII characters to exist in source code outside of comments.
		+
		+	=== Rationale ===
		+
		+	Using a consistent character encoding makes it easier to edit and copy code without needing to repeatedly re-encode the file.

@@ Line 88: / Line 88: @@
 == Comment formatting ==
-Comments to the right of code start in column 32.  Comments not to the right of code are indented at the prevailing indent for the surrounding code.  Make the comments complete sentences.  If you need more than one line, make them into block comments, like this:
+Comments to the right of code start in column 32.  Comments not to the right of code are indented at the prevailing indent for the surrounding code.  Make the comments complete sentences.  If you need more than two lines, use a block comment like this:
 <pre>
@@ Line 100: / Line 100: @@
 </pre>
-Really important single-line comments should also be done in block form:
+Important one-line or two-line comments should also be done in block form:
 <pre>
@@ Line 106: / Line 106: @@
  * This is a really important one-line comment.
  */
 </pre>

← Older revision		Revision as of 20:42, 2 October 2009
Line 64:		Line 64:

	Tab stop locations are not consistent across different editors and platforms, and can make code harder to read on a platform other than the one on which it was written. Tab characters also make diffs harder to read.		Tab stop locations are not consistent across different editors and platforms, and can make code harder to read on a platform other than the one on which it was written. Tab characters also make diffs harder to read.
		+
		+	Example:
		+
		+	<pre>
		+	1234567890123456780
		+	four spaces
		+	eight spaces
		+	tab
		+	</pre>

	== No trailing whitespace ==		== No trailing whitespace ==

← Older revision		Revision as of 20:40, 8 June 2009
Line 34:		Line 34:
	</pre>		</pre>

−	[needs more detail]
		+	This four-column basic offset is the increment of indentation. It is different from tab stops. In files that contain tab characters, the assumption is that tab stops are at every 8 columns. (This is the convention for Unix.) Therefore, in a file that uses tab characters, a line at the second indentation level will have a single tab character as its indentation. (We are attempting to phase out the use of tab characters.)

	=== Current conformance ===		=== Current conformance ===

@@ Line 229: / Line 229: @@
 Try to use a consistent form within a file.
-For function prototype declarations that are not part of a definition, do not omit parameter names, and try to place the return type name on the same line as the function name.  Also, try to avoid the above one-line-per-parameter style for prototypes.  Some function prototypes will have many characters preceding the function name, such as calling convention or other attribute macros; when combined with a long function name, this makes putting the function name at the beginning of a line a better idea:
+For function prototype declarations that are not part of a definition, do not omit parameter names, and try to place the return type name on the same line as the function name.  Also, try to avoid the above one-line-per-parameter style for prototypes.
 <pre>

@@ Line 55: / Line 55: @@
 == No tab characters ==
-No tab characters should appear in source files.  This guideline will probably be one of the more difficult ones to adopt in a non-disruptive manner.
+No tab characters should appear in source files.  This guideline will probably be one of the more difficult ones to adopt in a non-disruptive manner.  See [[Coding style/Transition strategies]] for one possibility.
 === Current conformance ===