svn commit: samba r23645 - in branches: SAMBA_3_0 SAMBA_3_0_25
SAMBA_3_0_26
jerry at samba.org
jerry at samba.org
Thu Jun 28 19:27:31 GMT 2007
Author: jerry
Date: 2007-06-28 19:27:30 +0000 (Thu, 28 Jun 2007)
New Revision: 23645
WebSVN: http://websvn.samba.org/cgi-bin/viewcvs.cgi?view=rev&root=samba&rev=23645
Log:
add examples and try to answer some common questions in the coding style guide
Modified:
branches/SAMBA_3_0/README.Coding
branches/SAMBA_3_0_25/README.Coding
branches/SAMBA_3_0_26/README.Coding
Changeset:
Modified: branches/SAMBA_3_0/README.Coding
===================================================================
--- branches/SAMBA_3_0/README.Coding 2007-06-28 18:09:37 UTC (rev 23644)
+++ branches/SAMBA_3_0/README.Coding 2007-06-28 19:27:30 UTC (rev 23645)
@@ -59,14 +59,14 @@
--
(Thanks to SATOH Fumiyasu <fumiyas at osstech.jp> for these hints):
-For the basic vi eitor including with all variants of *nix, add the
+For the basic vi editor including with all variants of *nix, add the
following to $HOME/.exrc:
set tabstop=8
set shiftwidth=8
For Vim, the following settings in $HOME/.vimrc will also deal with
-disaplaying trailing whitespace:
+displaying trailing whitespace:
if has("syntax") && (&t_Co > 2 || has("gui_running"))
syntax on
@@ -78,10 +78,138 @@
endif
-===================
-Statement Reference
-===================
+=========================
+FAQ & Statement Reference
+=========================
-To be filled later in as needed.
+Comments
+--------
+Comments should always use the standard C syntax. I.e. /* ... */. C++
+style comments are not currently allowed.
+
+Indention & Whitespace & 80 columns
+-----------------------------------
+
+To avoid confusion, indentations are to be 8 character with tab (not
+8 ' ' characters. When wrapping parameters for function calls,
+alignment parameter list with the first parameter on the previous line.
+Use tabs to get as close as possible and then fill in the final 7
+characters or less with whitespace. For example,
+
+ var1 = foo(arg1, arg2,
+ arg3);
+
+The previous example is intended to illustrate alignment of function
+parameters across lines and not as encourage for gratuitous line
+splitting. Never split a line before columns 70 - 79 unless you
+have a really good reason. Be smart about formatting.
+
+
+If, switch, & Code blocks
+-------------------------
+
+Always follow an 'if' keyword with a space but don't include additional
+spaces following or preceding the parentheses in the conditional.
+This is good:
+
+ if (x == 1)
+
+This is bad:
+
+ if ( x == 1 )
+
+Yes we have a lot of code that uses the second form and we are trying
+to clean it up without being overly intrusive.
+
+Note that this is a rule about parentheses following keywords and not
+functions. Don't insert a space between the name and left parentheses when
+invoking functions.
+
+Braces for code blocks used by for, if, switch, while, do..while, etc...
+should begin on the same line as the statement keyword and end on a line
+of their own. NOTE: Functions are different and the beginning left brace
+should begin on a line of its own.
+
+If the beginning statement has to be broken across lines due to length,
+the beginning brace should be on a line of its own.
+
+The exception to the ending rule is when the closing brace is followed by
+another language keyword such as else or the closing while in a do..while
+loop.
+
+Good examples:
+
+ if (x == 1) {
+ printf("good\n");
+ }
+
+ for (x=1;
+ x<10;
+ x++)
+ {
+ print("%d\n", x);
+ }
+
+ do {
+ printf("also good\n");
+ } while (1);
+
+Bad examples:
+
+ while (1)
+ {
+ print("I'm in a loop!\n"); }
+
+
+Goto
+----
+
+While many people have been academically taught that goto's are fundamentally
+evil, then can greatly enhance readability and reduce memory leaks when used
+as the single exit point from a function. But in no Samba world what so ever
+is a goto outside of a function or block of code a good idea.
+
+Good Examples:
+
+int function foo(int y)
+{
+ int *z = NULL;
+ int ret = 0;
+
+ if ( y < 10 ) {
+ z = malloc(sizeof(int)*y);
+ if (!z) {
+ ret = 1;
+ goto done;
+ }
+ }
+
+ print("Allocated %d elements.\n", y);
+
+ done:
+ if (z)
+ free(z);
+
+ return ret;
+}
+
+
+Checking Pointer Values
+-----------------------
+
+When invoking functions that return pointer values, either of the following
+are acceptable. Use you best judgement and choose the more readable option.
+Remember that many other people will review it.
+
+ if ((x = malloc(sizeof(short)*10)) == NULL ) {
+ fprintf(stderr, "Unable to alloc memory!\n");
+ }
+
+or
+
+ x = malloc(sizeof(short)*10);
+ if (!x) {
+ fprintf(stderr, "Unable to alloc memory!\n");
+ }
Modified: branches/SAMBA_3_0_25/README.Coding
===================================================================
--- branches/SAMBA_3_0_25/README.Coding 2007-06-28 18:09:37 UTC (rev 23644)
+++ branches/SAMBA_3_0_25/README.Coding 2007-06-28 19:27:30 UTC (rev 23645)
@@ -59,14 +59,14 @@
--
(Thanks to SATOH Fumiyasu <fumiyas at osstech.jp> for these hints):
-For the basic vi eitor including with all variants of *nix, add the
+For the basic vi editor including with all variants of *nix, add the
following to $HOME/.exrc:
set tabstop=8
set shiftwidth=8
For Vim, the following settings in $HOME/.vimrc will also deal with
-disaplaying trailing whitespace:
+displaying trailing whitespace:
if has("syntax") && (&t_Co > 2 || has("gui_running"))
syntax on
@@ -78,10 +78,138 @@
endif
-===================
-Statement Reference
-===================
+=========================
+FAQ & Statement Reference
+=========================
-To be filled later in as needed.
+Comments
+--------
+Comments should always use the standard C syntax. I.e. /* ... */. C++
+style comments are not currently allowed.
+
+Indention & Whitespace & 80 columns
+-----------------------------------
+
+To avoid confusion, indentations are to be 8 character with tab (not
+8 ' ' characters. When wrapping parameters for function calls,
+alignment parameter list with the first parameter on the previous line.
+Use tabs to get as close as possible and then fill in the final 7
+characters or less with whitespace. For example,
+
+ var1 = foo(arg1, arg2,
+ arg3);
+
+The previous example is intended to illustrate alignment of function
+parameters across lines and not as encourage for gratuitous line
+splitting. Never split a line before columns 70 - 79 unless you
+have a really good reason. Be smart about formatting.
+
+
+If, switch, & Code blocks
+-------------------------
+
+Always follow an 'if' keyword with a space but don't include additional
+spaces following or preceding the parentheses in the conditional.
+This is good:
+
+ if (x == 1)
+
+This is bad:
+
+ if ( x == 1 )
+
+Yes we have a lot of code that uses the second form and we are trying
+to clean it up without being overly intrusive.
+
+Note that this is a rule about parentheses following keywords and not
+functions. Don't insert a space between the name and left parentheses when
+invoking functions.
+
+Braces for code blocks used by for, if, switch, while, do..while, etc...
+should begin on the same line as the statement keyword and end on a line
+of their own. NOTE: Functions are different and the beginning left brace
+should begin on a line of its own.
+
+If the beginning statement has to be broken across lines due to length,
+the beginning brace should be on a line of its own.
+
+The exception to the ending rule is when the closing brace is followed by
+another language keyword such as else or the closing while in a do..while
+loop.
+
+Good examples:
+
+ if (x == 1) {
+ printf("good\n");
+ }
+
+ for (x=1;
+ x<10;
+ x++)
+ {
+ print("%d\n", x);
+ }
+
+ do {
+ printf("also good\n");
+ } while (1);
+
+Bad examples:
+
+ while (1)
+ {
+ print("I'm in a loop!\n"); }
+
+
+Goto
+----
+
+While many people have been academically taught that goto's are fundamentally
+evil, then can greatly enhance readability and reduce memory leaks when used
+as the single exit point from a function. But in no Samba world what so ever
+is a goto outside of a function or block of code a good idea.
+
+Good Examples:
+
+int function foo(int y)
+{
+ int *z = NULL;
+ int ret = 0;
+
+ if ( y < 10 ) {
+ z = malloc(sizeof(int)*y);
+ if (!z) {
+ ret = 1;
+ goto done;
+ }
+ }
+
+ print("Allocated %d elements.\n", y);
+
+ done:
+ if (z)
+ free(z);
+
+ return ret;
+}
+
+
+Checking Pointer Values
+-----------------------
+
+When invoking functions that return pointer values, either of the following
+are acceptable. Use you best judgement and choose the more readable option.
+Remember that many other people will review it.
+
+ if ((x = malloc(sizeof(short)*10)) == NULL ) {
+ fprintf(stderr, "Unable to alloc memory!\n");
+ }
+
+or
+
+ x = malloc(sizeof(short)*10);
+ if (!x) {
+ fprintf(stderr, "Unable to alloc memory!\n");
+ }
Modified: branches/SAMBA_3_0_26/README.Coding
===================================================================
--- branches/SAMBA_3_0_26/README.Coding 2007-06-28 18:09:37 UTC (rev 23644)
+++ branches/SAMBA_3_0_26/README.Coding 2007-06-28 19:27:30 UTC (rev 23645)
@@ -59,14 +59,14 @@
--
(Thanks to SATOH Fumiyasu <fumiyas at osstech.jp> for these hints):
-For the basic vi eitor including with all variants of *nix, add the
+For the basic vi editor including with all variants of *nix, add the
following to $HOME/.exrc:
set tabstop=8
set shiftwidth=8
For Vim, the following settings in $HOME/.vimrc will also deal with
-disaplaying trailing whitespace:
+displaying trailing whitespace:
if has("syntax") && (&t_Co > 2 || has("gui_running"))
syntax on
@@ -78,10 +78,138 @@
endif
-===================
-Statement Reference
-===================
+=========================
+FAQ & Statement Reference
+=========================
-To be filled later in as needed.
+Comments
+--------
+Comments should always use the standard C syntax. I.e. /* ... */. C++
+style comments are not currently allowed.
+
+Indention & Whitespace & 80 columns
+-----------------------------------
+
+To avoid confusion, indentations are to be 8 character with tab (not
+8 ' ' characters. When wrapping parameters for function calls,
+alignment parameter list with the first parameter on the previous line.
+Use tabs to get as close as possible and then fill in the final 7
+characters or less with whitespace. For example,
+
+ var1 = foo(arg1, arg2,
+ arg3);
+
+The previous example is intended to illustrate alignment of function
+parameters across lines and not as encourage for gratuitous line
+splitting. Never split a line before columns 70 - 79 unless you
+have a really good reason. Be smart about formatting.
+
+
+If, switch, & Code blocks
+-------------------------
+
+Always follow an 'if' keyword with a space but don't include additional
+spaces following or preceding the parentheses in the conditional.
+This is good:
+
+ if (x == 1)
+
+This is bad:
+
+ if ( x == 1 )
+
+Yes we have a lot of code that uses the second form and we are trying
+to clean it up without being overly intrusive.
+
+Note that this is a rule about parentheses following keywords and not
+functions. Don't insert a space between the name and left parentheses when
+invoking functions.
+
+Braces for code blocks used by for, if, switch, while, do..while, etc...
+should begin on the same line as the statement keyword and end on a line
+of their own. NOTE: Functions are different and the beginning left brace
+should begin on a line of its own.
+
+If the beginning statement has to be broken across lines due to length,
+the beginning brace should be on a line of its own.
+
+The exception to the ending rule is when the closing brace is followed by
+another language keyword such as else or the closing while in a do..while
+loop.
+
+Good examples:
+
+ if (x == 1) {
+ printf("good\n");
+ }
+
+ for (x=1;
+ x<10;
+ x++)
+ {
+ print("%d\n", x);
+ }
+
+ do {
+ printf("also good\n");
+ } while (1);
+
+Bad examples:
+
+ while (1)
+ {
+ print("I'm in a loop!\n"); }
+
+
+Goto
+----
+
+While many people have been academically taught that goto's are fundamentally
+evil, then can greatly enhance readability and reduce memory leaks when used
+as the single exit point from a function. But in no Samba world what so ever
+is a goto outside of a function or block of code a good idea.
+
+Good Examples:
+
+int function foo(int y)
+{
+ int *z = NULL;
+ int ret = 0;
+
+ if ( y < 10 ) {
+ z = malloc(sizeof(int)*y);
+ if (!z) {
+ ret = 1;
+ goto done;
+ }
+ }
+
+ print("Allocated %d elements.\n", y);
+
+ done:
+ if (z)
+ free(z);
+
+ return ret;
+}
+
+
+Checking Pointer Values
+-----------------------
+
+When invoking functions that return pointer values, either of the following
+are acceptable. Use you best judgement and choose the more readable option.
+Remember that many other people will review it.
+
+ if ((x = malloc(sizeof(short)*10)) == NULL ) {
+ fprintf(stderr, "Unable to alloc memory!\n");
+ }
+
+or
+
+ x = malloc(sizeof(short)*10);
+ if (!x) {
+ fprintf(stderr, "Unable to alloc memory!\n");
+ }
More information about the samba-cvs
mailing list