4. Coding + Guidelines

Explanation:

-/* if page size greater than 1k ... */
+    
+      4.2. Using Comments
+      
+        4.2.1. Comment, Comment,
+        Comment
+        Explanation:
+        Comment as much as possible without commenting the obvious. For
+        example do not comment "variable_a is equal to variable_b". Instead
+        explain why variable_a should be equal to the variable_b. Just
+        because a person can read code does not mean they will understand why
+        or what is being done. A reader may spend a lot more time figuring
+        out what is going on when a simple comment or explanation would have
+        prevented the extra research. Please help your fellow Privoxy
+        developers out!
+        The comments will also help justify the intent of the code. If the
+        comment describes something different than what the code is doing
+        then maybe a programming error is occurring.
+        Example:
+        
+          
+            
-            
-          
+              +              /* if page size greater than 1k ... */
 if (page_length() > 1024)
 {
     ... "block" the page up ...
@@ -107,35 +82,27 @@ if (page_length() > 1024)
 
 This demonstrates 2 cases of "what not to do".  The first is a
 "syntax comment".  The second is a comment that does not fit what
-is actually being done.
-
-              
-        
-        
-          
-            4.2.2. Use blocks for comments
-          
-          
-            Explanation:
-          
-          
-            Comments can help or they can clutter. They help when they are
-            differentiated from the code they describe. One line comments do
-            not offer effective separation between the comment and the code.
-            Block identifiers do, by surrounding the code with a clear,
-            definable pattern.
-          
-          
-            Example:
-          
-          
-            
-              
+          
+        
--/*********************************************************************
+is actually being done.
+            
+      
+      
+        4.2.2. Use blocks for
+        comments
+        Explanation:
+        Comments can help or they can clutter. They help when they are
+        differentiated from the code they describe. One line comments do not
+        offer effective separation between the comment and the code. Block
+        identifiers do, by surrounding the code with a clear, definable
+        pattern.
+        Example:
+        
+          
+            
-            
-          
+              +              /*********************************************************************
  * This will stand out clearly in your code!
  *********************************************************************/
 if (this_variable == that_variable)
@@ -154,46 +121,33 @@ if (this_variable == that_variable)
 if (this_variable == that_variable) /* this may not either */
 {
    do_something_very_important();
-}
-
-              
-          
-            Exception:
-          
-          
-            If you are trying to add a small logic comment and do not 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.
-          
-        
-        
-          
-            4.2.3. Keep Comments on their own line
-          
-          
-            Explanation:
-          
-          
-            It goes back to the question of readability. If the comment is on
-            the same line as the code it will be harder to read than the
-            comment that is on its own line.
-          
-          
-            There are three exceptions to this rule, which should be violated
-            freely and often: during the definition of variables, at the end
-            of closing braces, when used to comment parameters.
-          
-          
-            Example:
-          
-          
-            
-              
+          
+        
--/*********************************************************************
+}
+            
+        Exception:
+        If you are trying to add a small logic comment and do not 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.
+      
+      
+        4.2.3. Keep Comments on their
+        own line
+        Explanation:
+        It goes back to the question of readability. If the comment is on
+        the same line as the code it will be harder to read than the comment
+        that is on its own line.
+        There are three exceptions to this rule, which should be violated
+        freely and often: during the definition of variables, at the end of
+        closing braces, when used to comment parameters.
+        Example:
+        
+          
+            
-            
-          
+              +              /*********************************************************************
  * This will stand out clearly in your code,
  * But the second example won't.
  *********************************************************************/
@@ -226,89 +180,60 @@ short do_something_very_important(
 {
    ...code here...
 
-}   /* -END- do_something_very_important */
-
-              
-        
-        
-          
-            4.2.4. Comment each logical step
-          
-          
-            Explanation:
-          
-          
-            Logical steps should be commented to help others follow the
-            intent of the written code and comments will make the code more
-            readable.
-          
-          
-            If you have 25 lines of code without a comment, you should
-            probably go back into it to see where you forgot to put one.
-          
-          
-            Most "for", "while", "do", etc... loops _probably_ need a
-            comment. After all, these are usually major logic containers.
-          
-        
-        
-          
-            4.2.5. Comment All Functions Thoroughly
-          
-          
-            Explanation:
-          
-          
-            A reader of the code should be able to look at the comments just
-            prior to the beginning of a function and discern the reason for
-            its existence and the consequences of using it. The reader should
-            not have to read through the code to determine if a given
-            function is safe for a desired use. The proper information
-            thoroughly presented at the introduction of a function not only
-            saves time for subsequent maintenance or debugging, it more
-            importantly aids in code reuse by allowing a user to determine
-            the safety and applicability of any function for the problem at
-            hand. As a result of such benefits, all functions should contain
-            the information presented in the addendum section of this
-            document.
-          
-        
-        
-          
-            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
-            comment that describes the origination of the brace if the
-            original brace is off of the screen, or otherwise far away from
-            the closing brace. This will simplify the debugging, maintenance,
-            and readability of the code.
-          
-          
-            As a suggestion , use the following flags to make the comment and
-            its brace more readable:
-          
-          
-            use following a closing brace: } /* -END- if() or while () or
-            etc... */
-          
-          
-            Example:
-          
-          
-            
-              
+          
+        
--if (1 == X)
+}   /* -END- do_something_very_important */
+            
+      
+      
+        4.2.4. Comment each logical
+        step
+        Explanation:
+        Logical steps should be commented to help others follow the intent
+        of the written code and comments will make the code more
+        readable.
+        If you have 25 lines of code without a comment, you should
+        probably go back into it to see where you forgot to put one.
+        Most "for", "while", "do", etc... loops _probably_ need a comment.
+        After all, these are usually major logic containers.
+      
+      
+        4.2.5. Comment All Functions
+        Thoroughly
+        Explanation:
+        A reader of the code should be able to look at the comments just
+        prior to the beginning of a function and discern the reason for its
+        existence and the consequences of using it. The reader should not
+        have to read through the code to determine if a given function is
+        safe for a desired use. The proper information thoroughly presented
+        at the introduction of a function not only saves time for subsequent
+        maintenance or debugging, it more importantly aids in code reuse by
+        allowing a user to determine the safety and applicability of any
+        function for the problem at hand. As a result of such benefits, all
+        functions should contain the information presented in the addendum
+        section of this document.
+      
+      
+        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
+        comment that describes the origination of the brace if the original
+        brace is off of the screen, or otherwise far away from the closing
+        brace. This will simplify the debugging, maintenance, and readability
+        of the code.
+        As a suggestion , use the following flags to make the comment and
+        its brace more readable:
+        use following a closing brace: } /* -END- if() or while () or
+        etc... */
+        Example:
+        
+          
+            
-            
-          
+              if (1 == X)
 {
    do_something_very_important();
    ...some long list of commands...
@@ -320,476 +245,325 @@ if (1 == X)
 {
    do_something_very_important();
    ...some long list of commands...
-} /* -END- if (1 == X) */
-
-              
-        
+} /* -END- if (1 == X) */

- Prev -	- Home -	- Next -
- Documentation Guidelines -	- -	- Testing Guidelines +}

Prev	Home	Next
Documentation + Guidelines		Testing Guidelines

- Prev -	- Home -	- Next -
- Introduction -	- -	- Documentation Guidelines -

Prev	Home	Next
Introduction		Documentation + Guidelines

- Prev -	- Home -	- Next -
- The CVS Repository -	- -	- Coding Guidelines -

- 4. Coding Guidelines -

- 4.1. Introduction -

- 4.2. Using Comments -

- 4.2.1. Comment, Comment, Comment -

- 4.2.2. Use blocks for comments -

- 4.2.3. Keep Comments on their own line -

- 4.2.4. Comment each logical step -

- 4.2.5. Comment All Functions Thoroughly -

- 4.2.6. Comment at the end of braces if the content - is more than one screen length -

- 4.3. Naming Conventions -

- 4.3.1. Variable Names -

- 4.3.2. Function Names -

- 4.3.3. Header file prototypes -

- 4.3.4. Enumerations, and #defines -

- 4.3.5. Constants -

- 4.4. Using Space -

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

- 4.4.2. ALL control statements should have a - block -

- 4.4.3. Do not belabor/blow-up boolean - expressions -

- 4.4.4. Use white space freely because it is - free -

- 4.4.5. Don't use white space around structure - operators -

- 4.4.6. Make the last brace of a function stand - out -

- 4.4.7. Use 3 character indentions -

- 4.5. Initializing -

- 4.5.1. Initialize all variables -

- 4.6. Functions -

- 4.6.1. Name functions that return a boolean as a - question. -

- 4.6.2. Always specify a return type for a - function. -

- 4.6.3. Minimize function calls when iterating by - using variables -

- 4.6.4. Pass and Return by Const Reference -

- 4.6.5. Pass and Return by Value -

- 4.6.6. Names of include files -

- 4.6.7. Provide multiple inclusion protection -

- 4.6.8. Use `extern "C"` when appropriate -

- 4.6.9. Where Possible, Use Forward Struct - Declaration Instead of Includes -

- 4.7. General Coding Practices -

- 4.7.1. Turn on warnings -

- 4.7.2. Provide a default case for all switch - statements -

- 4.7.3. Try to avoid falling through cases in a - switch statement. -

- 4.7.4. Don't mix size_t and other types -

- 4.7.5. Declare each variable and struct on its own - line. -

- 4.7.6. Use malloc/zalloc sparingly -

- 4.7.7. The Programmer Who Uses 'malloc' is - Responsible for Ensuring 'free' -

- 4.7.8. Add loaders to the `file_list' structure and - in order -

- 4.7.9. "Uncertain" new code and/or changes to - existing code, use XXX -

- 4.8. Addendum: Template for files and function - comment blocks: -

- 2. The CVS Repository -

- 2.1. Access to CVS -

- 2.2. Branches -

- 2.3. CVS Commit Guidelines -

- 3. Documentation Guidelines -

- 3.1. Quickstart to Docbook and SGML -

- 3.2. Privoxy - Documentation Style -

- 3.3. Privoxy Custom Entities -

- Privoxy Developer Manual -

- 1. Introduction -

- 1.1. Quickstart to Privoxy Development -

- 6. Releasing a New Version -

- 6.1. Version numbers -

- 6.2. Before the Release: Freeze -

- 6.3. Building and Releasing the Packages -

- 6.3.1. Note on Privoxy Packaging -

- 6.3.2. Source Tarball -

- 6.3.3. SuSE, Conectiva or Red Hat - RPM -

- 6.3.4. OS/2 -

- 6.3.5. Solaris -

- 6.3.6. Windows -

- 6.3.7. Debian -

- 6.3.8. Mac OS X -

- 6.3.8.1. - OSXPackageBuilder module -

- 6.3.8.2. osxsetup module - (DEPRECATED) -

- 6.3.8.3. macsetup module -

- 6.3.9. FreeBSD -

- 6.4. Uploading and Releasing Your Package -

- 6.5. After the Release -