| Next | 4.2.1. Comment, Comment, Comment
Exception:
If you are trying to add a small logic comment and do not @@ -236,9 +257,12 @@ NAME="S5" >4.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 @@ -335,9 +365,12 @@ NAME="S7" >4.2.5. Comment All Functions Thoroughly
Explanation:
A reader of the code should be able to look at the comments @@ -363,9 +396,12 @@ NAME="S8" 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 @@ -882,9 +999,12 @@ NAME="S18" 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 @@ -925,17 +1051,23 @@ NAME="S19" 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 @@ -1259,17 +1439,23 @@ NAME="S28" 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 @@ -1369,9 +1567,12 @@ NAME="S30" >4.6.5. Pass and Return by Value
Explanation:
Most structures cannot fit onto a normal stack entry (i.e. @@ -1391,9 +1592,12 @@ NAME="S31" >4.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.
Explanation:
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.
4.7.1. Turn on warningsExplanation
Compiler warnings are meant to help you find bugs. You @@ -1625,9 +1865,12 @@ NAME="S37" 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 @@ -1729,17 +1987,23 @@ NAME="S39" '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 @@ -1755,17 +2019,19 @@ NAME="S40" >4.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).
Explanation:
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 @@ -1962,12 +2270,15 @@ CLASS="SECT3" >4.7.10. "Uncertain" new code and/or changes to - existing code, use FIXME
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 @@ -2007,9 +2321,12 @@ NAME="S46" comment blocks:
Example for file comments:
const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.40 2002/05/04 00:43:43 hal9 Exp $"; +>const char FILENAME_rcs[] = "$Id$"; /********************************************************************* * * File : $Source$ * * Purpose : (Fill me in with a good description!) * - * Copyright : Written by and Copyright (C) 2001 the SourceForge - * Privoxy team. http://www.privoxy.org/ - * - * Based on the Internet Junkbuster originally written - * by and Copyright (C) 1997 Anonymous Coders and - * Junkbusters Corporation. http://www.junkbusters.com + * Copyright : Written by and Copyright (C) 2001-2009 + * the Privoxy team. http://www.privoxy.org/ * * This program is free software; you can redistribute it * and/or modify it under the terms of the GNU General @@ -2047,12 +2360,10 @@ 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. - * - * Revisions : - * $Log$ + * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html + * or write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 , + * USA * *********************************************************************/ @@ -2066,26 +2377,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 |