-
-
+
+
+
+
+
+ Explanation:
+
+
+ The brace needs to be on a line all by itself, not at the end of
+ the statement. Curly braces should line up with the construct
+ that they're associated with. This practice makes it easier to
+ identify the opening and closing braces for a block.
+
+
+ Example:
+
+
+
+
+
if (this == that)
{
...
}
- |
-
-
-
- Instead
- of:
-
- if (this == that) { ... }
-
- or
-
- if (this == that) { ... }
-
- Note: In the
- special case that the if-statement is inside a loop, and it is
- trivial, i.e. it tests for a condition that is obvious from the
- purpose of the block, one-liners as above may optically preserve the
- loop structure and make it easier to read.
-
- Status:
- developer-discretion.
-
- Example
- exception:
-
-
+
+ Instead of:
+
+
+ if (this == that) { ... }
+
+
+ or
+
+
+ if (this == that) { ... }
+
+
+ Note: In
+ the special case that the if-statement is inside a loop, and it
+ is trivial, i.e. it tests for a condition that is obvious from
+ the purpose of the block, one-liners as above may optically
+ preserve the loop structure and make it easier to read.
+
+
+ Status:
+ developer-discretion.
+
+
+ Example
+ exception:
+
+
+
+
+
while (more lines are read)
{
/* Please document what is/is not a comment line here */
@@ -577,151 +625,170 @@ while (more lines are read)
do_something(line);
}
- |
-
-
-
-
-
-
-
- Explanation:
-
- Using braces to make a block will make your code more readable and
- less prone to error. All control statements should have a block
- defined.
-
- Example:
-
-
+
+
+
+
+ Explanation:
+
+
+ Using braces to make a block will make your code more readable
+ and less prone to error. All control statements should have a
+ block defined.
+
+
+ Example:
+
+
+
+
+
if (this == that)
{
do_something();
do_something_else();
}
- |
-
-
-
- Instead
- of:
-
- if (this == that) do_something(); do_something_else();
-
- or
-
- if (this == that) do_something();
-
- Note: The
- first example in "Instead of" will execute in a manner other than
- that which the developer desired (per indentation). Using code braces
- would have prevented this "feature". The "explanation" and
- "exception" from the point above also applies.
-
-
-
-
-
- Example:
-
-
+
+ Instead of:
+
+
+ if (this == that) do_something(); do_something_else();
+
+
+ or
+
+
+ if (this == that) do_something();
+
+
+ Note: The
+ first example in "Instead of" will execute in a manner other than
+ that which the developer desired (per indentation). Using code
+ braces would have prevented this "feature". The "explanation" and
+ "exception" from the point above also applies.
+
+
+
+
+
+ Example:
+
+
+
+
+
structure->flag = (condition);
- |
-
-
-
- Instead
- of:
-
- if (condition) { structure->flag = 1; } else {
- structure->flag = 0; }
-
- Note: The
- former is readable and concise. The later is wordy and inefficient.
- Please assume that any developer new to the project has at least a
- "good" knowledge of C/C++. (Hope I do not offend by that last comment
- ... 8-)
-
-
-
-
-
- Explanation:
-
- Make it readable. The notable exception to using white space
- freely is listed in the next guideline.
-
- Example:
-
-
+
+ Instead of:
+
+
+ if (condition) { structure->flag = 1; } else {
+ structure->flag = 0; }
+
+
+ Note: The
+ former is readable and concise. The later is wordy and
+ inefficient. Please assume that any developer new to the project
+ has at least a "good" knowledge of C/C++. (Hope I do not offend
+ by that last comment ... 8-)
+
+
+
+
+
+ Explanation:
+
+
+ Make it readable. The notable exception to using white space
+ freely is listed in the next guideline.
+
+
+ Example:
+
+
+
+
+
int first_value = 0;
int some_value = 0;
int another_value = 0;
int this_variable = 0;
- |
-
-
-
-
-
-
-
- Explanation:
-
- - structure pointer operator ( "->" ) - member operator ( "." )
- - functions and parentheses
-
- It is a general coding practice to put pointers, references, and
- function parentheses next to names. With spaces, the connection
- between the object and variable/function name is not as clear.
-
- Example:
-
-
+
+
+
+
+ Explanation:
+
+
+ - structure pointer operator ( "->" ) - member operator ( "."
+ ) - functions and parentheses
+
+
+ It is a general coding practice to put pointers, references, and
+ function parentheses next to names. With spaces, the connection
+ between the object and variable/function name is not as clear.
+
+
+ Example:
+
+
+
+
+
a_struct->a_member;
a_struct.a_member;
function_name();
- |
-
-
-
- Instead of:
- a_struct -> a_member; a_struct . a_member; function_name ();
-
-
-
-
-
- Example:
-
-
+
+ Instead of:
+ a_struct -> a_member; a_struct . a_member; function_name ();
+
+
+
+
+
+ Example:
+
+
+
+
+
int function1( ... )
{
...code...
@@ -734,47 +801,52 @@ int function2( ... )
{
} /* -END- function2 */
- |
-
-
-
- Instead
- of:
-
- int function1( ... ) { ...code... return(ret_code); } int
- function2( ... ) { }
-
- Note: Use 1
- blank line before the closing brace and 2 lines afterward. This makes
- the end of function standout to the most casual viewer. Although
- function comments help separate functions, this is still a good
- coding practice. In fact, I follow these rules when using blocks in
- "for", "while", "do" loops, and long if {} statements too. After all
- whitespace is free!
-
- Status:
- developer-discretion on the number of blank lines. Enforced is the
- end of function comments.
-
-
-
-
-
- Explanation:
-
- If some use 8 character TABs and some use 3 character TABs, the
- code can look *very* ragged. So use 3 character indentions only. If
- you like to use TABs, pass your code through a filter such as "expand
- -t3" before checking in your code.
-
- Example:
-
-
+
+ Instead of:
+
+
+ int function1( ... ) { ...code... return(ret_code); } int
+ function2( ... ) { }
+
+
+ Note: Use 1
+ blank line before the closing brace and 2 lines afterward. This
+ makes the end of function standout to the most casual viewer.
+ Although function comments help separate functions, this is still
+ a good coding practice. In fact, I follow these rules when using
+ blocks in "for", "while", "do" loops, and long if {} statements
+ too. After all whitespace is free!
+
+
+ Status:
+ developer-discretion on the number of blank lines. Enforced is
+ the end of function comments.
+
+
+
+
+
+ Explanation:
+
+
+ If some use 8 character TABs and some use 3 character TABs, the
+ code can look *very* ragged. So use 3 character indentions only.
+ If you like to use TABs, pass your code through a filter such as
+ "expand -t3" before checking in your code.
+
+
+ Example:
+
+
+
+
+
static const char * const url_code_map[256] =
{
NULL, ...
@@ -793,139 +865,157 @@ int function1( ... )
}
return NEVER_GETS_HERE;
-
-}
-
- |
-
-
-
-
-
-
-
-
-
- Explanation:
-
- Do not assume that the variables declared will not be used until
- after they have been assigned a value somewhere else in the code.
- Remove the chance of accidentally using an unassigned variable.
-
- Example:
-
-
-
-
-
-short a_short = 0;
-float a_float = 0;
-struct *ptr = NULL;
-
- |
-
-
-
- Note: It is
- much easier to debug a SIGSEGV if the message says you are trying to
- access memory address 00000000 and not 129FA012; or array_ptr[20]
- causes a SIGSEV vs. array_ptr[0].
-
- Status:
- developer-discretion if and only if the variable is assigned a value
- "shortly after" declaration.
-
-
-
-
-
-
-
- Explanation:
-
- Value should be phrased as a question that would logically be
- answered as a true or false statement
-
- Example:
-
-
+
+
+
+
+
+
+ Explanation:
+
+
+ Do not assume that the variables declared will not be used until
+ after they have been assigned a value somewhere else in the code.
+ Remove the chance of accidentally using an unassigned variable.
+
+
+ Example:
+
+
+
+
+
+short a_short = 0;
+float a_float = 0;
+struct *ptr = NULL;
+
+ |
+
+
+
+ Note: It is
+ much easier to debug a SIGSEGV if the message says you are trying
+ to access memory address 00000000 and not 129FA012; or
+ array_ptr[20] causes a SIGSEV vs. array_ptr[0].
+
+
+ Status:
+ developer-discretion if and only if the variable is assigned a
+ value "shortly after" declaration.
+
+
+
+
+
+
+
+ Explanation:
+
+
+ Value should be phrased as a question that would logically be
+ answered as a true or false statement
+
+
+ Example:
+
+
+
+
+
should_we_block_this();
contains_an_image();
is_web_page_blank();
- |
-
-
-
-
-
-
-
- Explanation:
-
- The default return for a function is an int. To avoid ambiguity,
- create a return for a function when the return has a purpose, and
- create a void return type if the function does not need to return
- anything.
-
-
-
-
-
- Explanation:
-
- It is easy to write the following code, and a clear argument can
- be made that the code is easy to understand:
-
- Example:
-
-
+
+
+
+
+ Explanation:
+
+
+ The default return for a function is an int. To avoid ambiguity,
+ create a return for a function when the return has a purpose, and
+ create a void return type if the function does not need to return
+ anything.
+
+
+
+
+
+ Explanation:
+
+
+ It is easy to write the following code, and a clear argument can
+ be made that the code is easy to understand:
+
+
+ Example:
+
+
+
+
+
for (size_t cnt = 0; cnt < block_list_length(); cnt++)
{
....
}
- |
-
-
-
- Note:
- Unfortunately, this makes a function call for each and every
- iteration. This increases the overhead in the program, because the
- compiler has to look up the function each time, call it, and return a
- value. Depending on what occurs in the block_list_length() call, it
- might even be creating and destroying structures with each iteration,
- even though in each case it is comparing "cnt" to the same value,
- over and over. Remember too - even a call to block_list_length() is a
- function call, with the same overhead.
-
- Instead of using a function call during the iterations, assign the
- value to a variable, and evaluate using the variable.
-
- Example:
-
-
+
+ Note:
+ Unfortunately, this makes a function call for each and every
+ iteration. This increases the overhead in the program, because
+ the compiler has to look up the function each time, call it, and
+ return a value. Depending on what occurs in the
+ block_list_length() call, it might even be creating and
+ destroying structures with each iteration, even though in each
+ case it is comparing "cnt" to the same value, over and over.
+ Remember too - even a call to block_list_length() is a function
+ call, with the same overhead.
+
+
+ Instead of using a function call during the iterations, assign
+ the value to a variable, and evaluate using the variable.
+
+
+ Example:
+
+
+
+
+
size_t len = block_list_length();
for (size_t cnt = 0; cnt < len; cnt++)
@@ -933,144 +1023,161 @@ for (size_t cnt = 0; cnt < len; cnt++)
....
}
- |
-
-
-
- Exceptions:
- if the value of block_list_length() *may* change or could
- *potentially* change, then you must code the function call in the
- for/while loop.
-
-
-
-
-
- Explanation:
-
- This allows a developer to define a const pointer and call your
- function. If your function does not have the const keyword, we may
- not be able to use your function. Consider strcmp, if it were defined
- as: extern int strcmp(char *s1, char *s2);
-
- I could then not use it to compare argv's in main: int main(int
- argc, const char *argv[]) { strcmp(argv[0], "privoxy"); }
-
- Both these pointers are *const*! If the c runtime library
- maintainers do it, we should too.
-
-
-
-
-
- Explanation:
-
- Most structures cannot fit onto a normal stack entry (i.e. they
- are not 4 bytes or less). Aka, a function declaration like: int
- load_aclfile(struct client_state csp)
-
- would not work. So, to be consistent, we should declare all
- prototypes with "pass by value": int load_aclfile(struct client_state
- *csp)
-
-
-
-
-
- Explanation:
-
- Your include statements should contain the file name without a
- path. The path should be listed in the Makefile, using -I as
- processor directive to search the indicated paths. An exception to
- this would be for some proprietary software that utilizes a partial
- path to distinguish their header files from system or other header
- files.
-
- Example:
-
-
+
+ Exceptions:
+ if the value of block_list_length() *may* change or could
+ *potentially* change, then you must code the function call in the
+ for/while loop.
+
+
+
+
+
+ Explanation:
+
+
+ This allows a developer to define a const pointer and call your
+ function. If your function does not have the const keyword, we
+ may not be able to use your function. Consider strcmp, if it were
+ defined as: extern int strcmp(char *s1, char *s2);
+
+
+ I could then not use it to compare argv's in main: int main(int
+ argc, const char *argv[]) { strcmp(argv[0], "privoxy"); }
+
+
+ Both these pointers are *const*! If the c runtime library
+ maintainers do it, we should too.
+
+
+
+
+
+ Explanation:
+
+
+ Most structures cannot fit onto a normal stack entry (i.e. they
+ are not 4 bytes or less). Aka, a function declaration like: int
+ load_aclfile(struct client_state csp)
+
+
+ would not work. So, to be consistent, we should declare all
+ prototypes with "pass by value": int load_aclfile(struct
+ client_state *csp)
+
+
+
+
+
+ Explanation:
+
+
+ Your include statements should contain the file name without a
+ path. The path should be listed in the Makefile, using -I as
+ processor directive to search the indicated paths. An exception
+ to this would be for some proprietary software that utilizes a
+ partial path to distinguish their header files from system or
+ other header files.
+
+
+ Example:
+
+
+
+
+
#include <iostream.h> /* This is not a local include */
#include "config.h" /* This IS a local include */
- |
-
-
-
- Exception:
-
-
+
+ Exception:
+
+
+
+
+
/* This is not a local include, but requires a path element. */
#include <sys/fileName.h>
- |
-
-
-
- Note:
- Please! do not add "-I." to the Makefile without a _very_ good
- reason. This duplicates the #include "file.h" behavior.
-
-
-
-
-
- Explanation:
-
- Prevents compiler and linker errors resulting from redefinition of
- items.
-
- Wrap each header file with the following syntax to prevent
- multiple inclusions of the file. Of course, replace PROJECT_H with
- your file name, with "." Changed to "_", and make it uppercase.
-
- Example:
-
-
+
+
+ Note:
+ Please! do not add "-I." to the Makefile without a _very_ good
+ reason. This duplicates the #include "file.h" behavior.
+
+
+
+
+
+ Explanation:
+
+
+ Prevents compiler and linker errors resulting from redefinition
+ of items.
+
+
+ Wrap each header file with the following syntax to prevent
+ multiple inclusions of the file. Of course, replace PROJECT_H
+ with your file name, with "." Changed to "_", and make it
+ uppercase.
+
+
+ Example:
+
+
+
+
+
#ifndef PROJECT_H_INCLUDED
#define PROJECT_H_INCLUDED
...
#endif /* ndef PROJECT_H_INCLUDED */
- |
-
-
-
-
-
-
-
- Explanation:
-
- If our headers are included from C++, they must declare our
- functions as `extern "C"`. This has no cost in C, but increases the
- potential re-usability of our code.
-
- Example:
-
-
+
+
+
+
+ Explanation:
+
+
+ If our headers are included from C++, they must declare our
+ functions as `extern "C"`. This has no cost in C, but increases
+ the potential re-usability of our code.
+
+
+ Example:
+
+
+
+
+
#ifdef __cplusplus
extern "C"
{
@@ -1082,81 +1189,90 @@ extern "C"
}
#endif /* def __cplusplus */
- |
-
-
-
-
-
-
-
- Explanation:
-
- Useful in headers that include pointers to other struct's.
- Modifications to excess header files may cause needless compiles.
-
- Example:
-
-
+
+
+
+
+ Explanation:
+
+
+ Useful in headers that include pointers to other struct's.
+ Modifications to excess header files may cause needless compiles.
+
+
+ Example:
+
+
+
+
+
/*********************************************************************
* We're avoiding an include statement here!
*********************************************************************/
struct file_list;
extern file_list *xyz;
- |
-
-
-
- Note: If you
- declare "file_list xyz;" (without the pointer), then including the
- proper header file is necessary. If you only want to prototype a
- pointer, however, the header file is unnecessary.
-
- Status: Use
- with discretion.
-
-
-
-
-
-
-
- Explanation
-
- Compiler warnings are meant to help you find bugs. You should turn
- on as many as possible. With GCC, the switch is "-Wall". Try and fix
- as many warnings as possible.
+ |
+
+