| Next | 6. Coding Guidelines4. Coding Guidelines
Exception:
If you are trying to add a small logic comment and do not @@ -233,12 +254,15 @@ CLASS="SECT3" CLASS="SECT3" >6.2.3. Keep Comments on their own line4.2.3. Keep Comments on their own line
Explanation:
It goes back to the question of readability. If the comment @@ -250,9 +274,12 @@ CLASS="EMPHASIS" at the end of closing braces, when used to comment parameters.
Example:
Explanation:
Logical steps should be commented to help others follow the @@ -332,12 +362,15 @@ CLASS="SECT3" CLASS="SECT3" >6.2.5. Comment All Functions Thoroughly4.2.5. Comment All Functions Thoroughly
Explanation:
A reader of the code should be able to look at the comments @@ -359,13 +392,16 @@ CLASS="SECT3" CLASS="SECT3" >6.2.6. Comment at the end of braces if the +>4.2.6. Comment at the end of braces if the content is more than one screen length
Explanation:
Each closing brace should be followed on the same line by a @@ -380,9 +416,12 @@ CLASS="EMPHASIS" >use following a closing brace: } /* -END- if() or while () or etc... */
Example:
Instead of:
Instead of:
Instead of:
Note: We have a standard naming scheme for #defines that toggle a feature in the preprocessor: FEATURE_>, where > is a short (preferably 1 or 2 word) description.
Example:
Instead of:
Instead of:
if ( this == that ) { ... }
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 ) DoSomething(); DoSomethingElse();
if ( this == that ) do_something(); do_something_else();or
if ( this == that ) DoSomething();
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 @@ -878,13 +995,16 @@ CLASS="SECT3" CLASS="SECT3" >6.4.3. Do not belabor/blow-up boolean +>4.4.3. Do not belabor/blow-up boolean expressions
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 @@ -921,21 +1047,27 @@ CLASS="SECT3" CLASS="SECT3" >6.4.4. Use white space freely because it is +>4.4.4. Use white space freely because it is free
Explanation:
Make it readable. The notable exception to using white space freely is listed in the next guideline.
Example:
int firstValue = 0; -int someValue = 0; -int anotherValue = 0; -int thisVariable = 0; +>int first_value = 0; +int some_value = 0; +int another_value = 0; +int this_variable = 0; -if ( thisVariable == thatVariable ) +if ( this_variable == this_variable ) -firstValue = oldValue + ( ( someValue - anotherValue ) - whatever ) |
Explanation:
- structure pointer operator ( "->" ) - member operator ( @@ -980,9 +1115,12 @@ CLASS="EMPHASIS" connection between the object and variable/function name is not as clear.
Example:
aStruct->aMember; -aStruct.aMember; -FunctionName();a_struct->a_member; +a_struct.a_member; +function_name(); |
Instead of: aStruct -> aMember; aStruct . aMember; - FunctionName ();
a_struct -> a_member; a_struct . a_member; + function_name ();Example:
Instead of:
int function1( ... ) { ...code... return( retCode ); } int +>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 @@ -1061,9 +1211,12 @@ CLASS="EMPHASIS" "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, @@ -1086,9 +1242,12 @@ CLASS="EMPHASIS" only. If you like to use TABs, pass your code through a filter such as "expand -t3" before checking in your code.
Example:
short anShort = 0; -float aFloat = 0; +>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 arrayPtr[20] causes a SIGSEV vs. - arrayPtr[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:
ShouldWeBlockThis(); -ContainsAnImage(); -IsWebPageBlank();should_we_block_this(); +contains_an_image(); +is_web_page_blank(); |
Explanation:
The default return for a function is an int. To avoid @@ -1255,21 +1435,27 @@ CLASS="SECT3" CLASS="SECT3" >6.6.3. Minimize function calls when iterating by +>4.6.3. Minimize function calls when iterating by using variables
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 < blockListLength(); cnt ++ )
+>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 blockListLength() call, it might even be creating and + 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 blockListLength() is a function + 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 = blockListLength();
+>size_t len = block_list_length();
-for ( size_t cnt = 0; cnt < len; cnt ++ )
+for ( size_t cnt = 0; cnt < len; cnt++ )
{
....
} |
Exceptions: if the value of blockListLength() *may* - change or could *potentially* change, then you must code the +> 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 @@ -1366,12 +1564,15 @@ CLASS="SECT3" CLASS="SECT3" >6.6.5. Pass and Return by Value4.6.5. Pass and Return by Value
Explanation:
Most structures cannot fit onto a normal stack entry (i.e. @@ -1388,12 +1589,15 @@ CLASS="SECT3" CLASS="SECT3" >6.6.6. Names of include files4.6.6. Names of include files
Explanation:
Your include statements should contain the file name without @@ -1403,9 +1607,12 @@ CLASS="EMPHASIS" partial path to distinguish their header files from system or other header files.
Example:
Exception:
Note: Please! do not add "-I." to the Makefile without a _very_ good reason. This duplicates the #include "file.h" behavior.
6.6.7. Provide multiple inclusion +>4.6.7. Provide multiple inclusion protectionExplanation:
Prevents compiler and linker errors resulting from @@ -1471,9 +1687,12 @@ CLASS="EMPHASIS" with your file name, with "." Changed to "_", and make it uppercase.
Example:
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.
6.7. General Coding Practices4.7. General Coding PracticesExplanation
Compiler warnings are meant to help you find bugs. You @@ -1621,13 +1861,16 @@ CLASS="SECT3" CLASS="SECT3" >6.7.2. Provide a default case for all switch +>4.7.2. Provide a default case for all switch statements
Explanation:
What you think is guaranteed is never really guaranteed. The @@ -1635,9 +1878,12 @@ CLASS="EMPHASIS" someday will be passed. So, to protect yourself from the unknown, always have a default step in a switch statement.
Example:
Note: If you already have a default condition, you are obviously exempt from this point. Of note, most of the WIN32 code calls `DefWindowProc' after the switch statement. This API call *should* be included in a default statement.
Another Note: This is not so much a readability issue as a robust programming issue. The "anomaly code goes here" may be no more than a print to the STDERR stream (as in - load_config). Or it may really be an ABEND condition.
Status: Programmer discretion is advised.
Explanation:
In general, you will want to have a 'break' statement within @@ -1725,21 +1983,27 @@ CLASS="SECT3" CLASS="SECT3" >6.7.4. Use 'long' or 'short' Instead of +>4.7.4. Use 'long' or 'short' Instead of 'int'
Explanation:
On 32-bit platforms, int usually has the range of long. On 16-bit platforms, int has the range of short.
Status: open-to-debate. In the case of most FSF projects (including X/GNU-Emacs), there are typedefs to int4, int8, int16, (or equivalence ... I forget the exact typedefs @@ -1752,20 +2016,22 @@ CLASS="SECT3" CLASS="SECT3" >6.7.5. Don't mix size_t and other types4.7.5. Don't mix size_t and other types
Explanation:
The type of size_t varies across platforms. Do not make assumptions about whether it is signed or unsigned, or about how long it is. Do not compare a size_t against another variable of a different type (or even against a constant) - without casting one of the values. Try to avoid using size_t if - you can.
Explanation:
It can be tempting to declare a series of variables all on one line. Don't.
Example:
Instead of:
long a, b, c;
Explanation: - there is more room for comments on the individual variables - easier to add new variables without messing up the original ones - when searching on a variable to find its type, there is less clutter to "visually" eliminate
Exceptions: when you want to declare a bunch of loop variables or other trivial variables; feel free to declare them - on 1 line. You should, although, provide a good comment on + on one line. You should, although, provide a good comment on their functions.
Status: developer-discretion.
Explanation:
Create a local struct (on the stack) if the variable will @@ -1853,9 +2140,12 @@ CLASS="EMPHASIS" >Only "malloc" a struct (on the heap) if the variable's life will extend beyond the context of one function call.
Example:
Exceptions:
The developer cannot be expected to provide `free'ing functions for C run-time library functions ... such as `strdup'.
Status: developer-discretion. The "main" use of this standard is for allocating and freeing data structures (complex or nested).
6.7.9. Add loaders to the `file_list' structure +>4.7.9. Add loaders to the `file_list' structure and in orderExplanation:
I have ordered all of the "blocker" file code to be in alpha order. It is easier to add/read new blockers when you expect a certain order.
Note: It may appear that the alpha order is broken in places by POPUP tests coming before PCRS tests. But since POPUPs can also be referred to as KILLPOPUPs, it is clear that @@ -1961,13 +2269,16 @@ CLASS="SECT3" CLASS="SECT3" >6.7.10. "Uncertain" new code and/or changes to - existing code, use FIXME4.7.10. "Uncertain" new code and/or changes to + existing code, use FIXME or XXX
Explanation:
If you have enough confidence in new code or confidence in @@ -1988,9 +2299,12 @@ CLASS="EMPHASIS" >/* FIXME: new code that *may* break something else... */ ...new code here...
Note: If you make it clear that this may or may not be a "good thing (tm)", it will be easier to identify and include in the project (or conversely exclude from the @@ -2003,13 +2317,16 @@ CLASS="SECT2" CLASS="SECT2" >6.8. Addendum: Template for files and function +>4.8. Addendum: Template for files and function comment blocks:
Example for file comments:
const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.35 2002/04/17 15:16:15 oes Exp $"; +>const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.20 2008/06/14 13:21:24 fabiankeil Exp $"; /********************************************************************* * * File : $Source$ * * Purpose : (Fill me in with a good description!) * - * Copyright : Written by and Copyright (C) 2001 the SourceForge + * Copyright : Written by and Copyright (C) 2001-2007 the SourceForge * Privoxy team. http://www.privoxy.org/ * * Based on the Internet Junkbuster originally written @@ -2048,8 +2365,9 @@ CLASS="PROGRAMLISTING" * The GNU General Public License should be included with * this file. If not, you can view it at * http://www.gnu.org/copyleft/gpl.html - * or write to the Free Software Foundation, Inc., 59 - * Temple Place - Suite 330, Boston, MA 02111-1307, USA. + * or write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 , + * USA * * Revisions : * $Log$ @@ -2066,26 +2384,35 @@ const char FILENAME_h_rcs[] = FILENAME_H_VERSION; |
Note: This declares the rcs variables that should be added to the "show-proxy-args" page. If this is a brand new creation by you, you are free to change the "Copyright" section to represent the rights you wish to maintain.
Note: The formfeed character that is present right after the comment flower box is handy for (X|GNU)Emacs users to skip the verbiage and get to the heart of the code (via `forward-page' and `backward-page'). Please include it if you can.
Example for file header comments:
Example for function comments:
Note: If we all follow this practice, we should be able to parse our code to create a "self-documenting" web page.
| Home | Next |