X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fwebserver%2Fdeveloper-manual%2Fcoding.html;h=364af8e1ec08334212004b75ca48463bf9cdc737;hb=40f1317bc310955b90b71ac41d8e2fb1fde49d3c;hp=d136ce6a0cc702df9df1b56d13ff13ad7da42051;hpb=281c503f6d2799387e2dfac7fccdd3d885c6312e;p=privoxy.git diff --git a/doc/webserver/developer-manual/coding.html b/doc/webserver/developer-manual/coding.html index d136ce6a..364af8e1 100644 --- a/doc/webserver/developer-manual/coding.html +++ b/doc/webserver/developer-manual/coding.html @@ -13,8 +13,8 @@ REL="PREVIOUS" TITLE="Documentation Guidelines" HREF="documentation.html">Next5. Coding Guidelines4. Coding Guidelines
5.1. Introduction4.1. Introduction

This set of standards is designed to make our lives easier. It is @@ -102,7 +102,7 @@ CLASS="SECT2" CLASS="SECT2" >5.2. Using Comments4.2. Using Comments

5.2.1. Comment, Comment, Comment4.2.1. Comment, Comment, Comment

5.2.2. Use blocks for comments4.2.2. Use blocks for comments

If you are trying to add a small logic comment and do not - wish to "disrubt" the flow of the code, feel free to use a 1 + wish to "disrupt" the flow of the code, feel free to use a 1 line comment which is NOT on the same line as the code.

5.2.3. Keep Comments on their own line4.2.3. Keep Comments on their own line

5.2.4. Comment each logical step4.2.4. Comment each logical step

5.2.5. Comment All Functions Thoroughly4.2.5. Comment All Functions Thoroughly

5.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

5.3. Naming Conventions4.3. Naming Conventions

5.3.1. Variable Names4.3.1. Variable Names

Explanation:

Use all lowercase, and seperate words via an underscore +>Use all lowercase, and separate words via an underscore ('_'). Do not start an identifier with an underscore. (ANSI C reserves these for use by the compiler and system headers.) Do not use identifiers which are reserved in ANSI C++. (E.g. @@ -481,7 +481,7 @@ CLASS="SECT3" CLASS="SECT3" >5.3.2. Function Names4.3.2. Function Names

Explanation:

Use all lowercase, and seperate words via an underscore +>Use all lowercase, and separate words via an underscore ('_'). Do not start an identifier with an underscore. (ANSI C reserves these for use by the compiler and system headers.) Do not use identifiers which are reserved in ANSI C++. (E.g. @@ -539,7 +539,7 @@ CLASS="SECT3" CLASS="SECT3" >5.3.3. Header file prototypes4.3.3. Header file prototypes

5.3.4. Enumerations, and #defines4.3.4. Enumerations, and #defines

5.3.5. Constants4.3.5. Constants

5.4. Using Space4.4. Using Space

5.4.1. Put braces on a line by themselves.4.4.1. Put braces on a line by themselves.

Note: In the special case that the if-statement is inside a loop, and it is trivial, i.e. it tests for a - condidtion that is obvious from the purpose of the block, + 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-discrection.

developer-discretion.

5.4.2. ALL control statements should have a +>4.4.2. ALL control statements should have a block

5.4.3. Do not belabor/blow-up boolean +>4.4.3. Do not belabor/blow-up boolean expressions

Note: The former is readable and consice. The later +> 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-)

5.4.4. Use white space freely because it is +>4.4.4. Use white space freely because it is free

5.4.5. Don't use white space around structure +>4.4.5. Don't use white space around structure operators

5.4.6. Make the last brace of a function stand +>4.4.6. Make the last brace of a function stand out

Note: Use 1 blank line before the closing brace and 2 - lines afterwards. This makes the end of function standout to + lines afterward. This makes the end of function standout to the most casual viewer. Although function comments help - seperate functions, this is still a good coding practice. In + 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-discrection on the number of blank +> developer-discretion on the number of blank lines. Enforced is the end of function comments.

5.4.7. Use 3 character indentions4.4.7. Use 3 character indentions

5.5. Initializing4.5. Initializing

5.5.1. Initialize all variables4.5.1. Initialize all variables

Status: developer-discrection if and only if the +> developer-discretion if and only if the variable is assigned a value "shortly after" declaration.

5.6. Functions4.6. Functions
5.6.1. Name functions that return a boolean as a +>4.6.1. Name functions that return a boolean as a question.

5.6.2. Always specify a return type for a +>4.6.2. Always specify a return type for a function.

5.6.3. Minimize function calls when iterating by +>4.6.3. Minimize function calls when iterating by using variables

5.6.4. Pass and Return by Const Reference4.6.4. Pass and Return by Const Reference

5.6.5. Pass and Return by Value4.6.5. Pass and Return by Value

5.6.6. Names of include files4.6.6. Names of include files

Note: Please! do not add "-I." to the Makefile without a _very_ good reason. This duplicates the #include - "file.h" behaviour.

5.6.7. Provide multiple inclusion +>4.6.7. Provide multiple inclusion protection

5.6.8. Use `extern "C"` when appropriate4.6.8. Use `extern "C"` when appropriate

5.6.9. Where Possible, Use Forward Struct +>4.6.9. Where Possible, Use Forward Struct Declaration Instead of Includes

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 unneccessary.

Status: Use with discrection.

Use with discretion.

5.7. General Coding Practices4.7. General Coding Practices
5.7.1. Turn on warnings4.7.1. Turn on warnings

5.7.2. Provide a default case for all switch +>4.7.2. Provide a default case for all switch statements

Another Note: This is not so much a readability issue - as a robust programming issue. The "anomly code goes here" may + 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.

5.7.3. Try to avoid falling through cases in a +>4.7.3. Try to avoid falling through cases in a switch statement.

5.7.4. Use 'long' or 'short' Instead of +>4.7.4. Use 'long' or 'short' Instead of 'int'

5.7.5. Don't mix size_t and other types4.7.5. Don't mix size_t and other types

5.7.6. Declare each variable and struct on its +>4.7.6. Declare each variable and struct on its own line.

Status: developer-discrection.

developer-discretion.

5.7.7. Use malloc/zalloc sparingly4.7.7. Use malloc/zalloc sparingly

Explanation:

Create a local stuct (on the stack) if the variable will +>Create a local struct (on the stack) if the variable will live and die within the context of one function call.

Only "malloc" a struct (on the heap) if the variable's life @@ -1866,7 +1866,7 @@ WIDTH="100%" >

If a function creates a struct and stores a pointer to it in a
-list, then it should definately be allocated via `malloc'.
5.7.8. The Programmer Who Uses 'malloc' is +>4.7.8. The Programmer Who Uses 'malloc' is Responsible for Ensuring 'free'

Status: developer-discrection. The "main" use of this +> developer-discretion. The "main" use of this standard is for allocating and freeing data structures (complex or nested).

5.7.9. Add loaders to the `file_list' structure +>4.7.9. Add loaders to the `file_list' structure and in order

5.7.10. "Uncertain" new code and/or changes to - exitinst code, use FIXME4.7.10. "Uncertain" new code and/or changes to + existing code, use FIXME

If you have enough confidence in new code or confidence in - your changes, but are not *quite* sure of the reprocussions, + your changes, but are not *quite* sure of the repercussions, add this:

/* FIXME: this code has a logic error on platform XYZ, * - attempthing to fix */ #ifdef PLATFORM ...changed code here... + attempting to fix */ #ifdef PLATFORM ...changed code here... #endif

or:

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 conversly exclude from the + include in the project (or conversely exclude from the project).

5.8. Addendum: Template for files and function +>4.8. Addendum: Template for files and function comment blocks:

const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.27 2002/04/08 15:31:18 hal9 Exp $";
+>const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.45 2002/05/19 23:01:54 hal9 Exp $";
 /*********************************************************************
  *
  * File        :  $Source$
@@ -2079,7 +2079,7 @@ CLASS="EMPHASIS"
 >Note: The formfeed character that is present right
     after the comment flower box is handy for (X|GNU)Emacs users to
-    skip the verbige and get to the heart of the code (via
+    skip the verbiage and get to the heart of the code (via
     `forward-page' and `backward-page'). Please include it if you
     can.
#ifndef _FILENAME_H
 #define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.27 2002/04/08 15:31:18 hal9 Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.45 2002/05/19 23:01:54 hal9 Exp $"
 /*********************************************************************
  *
  * File        :  $Source$
@@ -2238,7 +2238,7 @@ WIDTH="33%"
 ALIGN="right"
 VALIGN="top"
 >NextVersion Control GuidelinesTesting Guidelines