fb4208fe2fd4b7361069d5c91296190966283eff
[privoxy.git] / doc / webserver / developer-manual / coding.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <HTML
3 ><HEAD
4 ><TITLE
5 >Coding Guidelines</TITLE
6 ><META
7 NAME="GENERATOR"
8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
9 REL="HOME"
10 TITLE="Privoxy Developer Manual"
11 HREF="index.html"><LINK
12 REL="PREVIOUS"
13 TITLE="Documentation Guidelines"
14 HREF="documentation.html"><LINK
15 REL="NEXT"
16 TITLE="Testing Guidelines"
17 HREF="testing.html"><LINK
18 REL="STYLESHEET"
19 TYPE="text/css"
20 HREF="../p_doc.css"><META
21 HTTP-EQUIV="Content-Type"
22 CONTENT="text/html;
23 charset=ISO-8859-1"></HEAD
24 ><BODY
25 CLASS="SECT1"
26 BGCOLOR="#EEEEEE"
27 TEXT="#000000"
28 LINK="#0000FF"
29 VLINK="#840084"
30 ALINK="#0000FF"
31 ><DIV
32 CLASS="NAVHEADER"
33 ><TABLE
34 SUMMARY="Header navigation table"
35 WIDTH="100%"
36 BORDER="0"
37 CELLPADDING="0"
38 CELLSPACING="0"
39 ><TR
40 ><TH
41 COLSPAN="3"
42 ALIGN="center"
43 >Privoxy Developer Manual</TH
44 ></TR
45 ><TR
46 ><TD
47 WIDTH="10%"
48 ALIGN="left"
49 VALIGN="bottom"
50 ><A
51 HREF="documentation.html"
52 ACCESSKEY="P"
53 >Prev</A
54 ></TD
55 ><TD
56 WIDTH="80%"
57 ALIGN="center"
58 VALIGN="bottom"
59 ></TD
60 ><TD
61 WIDTH="10%"
62 ALIGN="right"
63 VALIGN="bottom"
64 ><A
65 HREF="testing.html"
66 ACCESSKEY="N"
67 >Next</A
68 ></TD
69 ></TR
70 ></TABLE
71 ><HR
72 ALIGN="LEFT"
73 WIDTH="100%"></DIV
74 ><DIV
75 CLASS="SECT1"
76 ><H1
77 CLASS="SECT1"
78 ><A
79 NAME="CODING"
80 >4. Coding Guidelines</A
81 ></H1
82 ><DIV
83 CLASS="SECT2"
84 ><H2
85 CLASS="SECT2"
86 ><A
87 NAME="S1"
88 >4.1. Introduction</A
89 ></H2
90 ><P
91 >This set of standards is designed to make our lives easier.  It is
92     developed with the simple goal of helping us keep the "new and improved
93     <SPAN
94 CLASS="APPLICATION"
95 >Privoxy</SPAN
96 >" consistent and reliable. Thus making
97     maintenance easier and increasing chances of success of the
98     project.</P
99 ><P
100 >And that of course comes back to us as individuals. If we can
101     increase our development and product efficiencies then we can solve more
102     of the request for changes/improvements and in general feel good about
103     ourselves. ;-&#62;</P
104 ></DIV
105 ><DIV
106 CLASS="SECT2"
107 ><H2
108 CLASS="SECT2"
109 ><A
110 NAME="S2"
111 >4.2. Using Comments</A
112 ></H2
113 ><DIV
114 CLASS="SECT3"
115 ><H3
116 CLASS="SECT3"
117 ><A
118 NAME="S3"
119 >4.2.1. Comment, Comment, Comment</A
120 ></H3
121 ><P
122 ><SPAN
123 CLASS="emphasis"
124 ><I
125 CLASS="EMPHASIS"
126 >Explanation:</I
127 ></SPAN
128 ></P
129 ><P
130 >Comment as much as possible without commenting the obvious.
131     For example do not comment "variable_a is equal to variable_b".
132     Instead explain why variable_a should be equal to the variable_b.
133     Just because a person can read code does not mean they will
134     understand why or what is being done. A reader may spend a lot
135     more time figuring out what is going on when a simple comment
136     or explanation would have prevented the extra research. Please
137     help your fellow Privoxy developers out!</P
138 ><P
139 >The comments will also help justify the intent of the code.
140     If the comment describes something different than what the code
141     is doing then maybe a programming error is occurring.</P
142 ><P
143 ><SPAN
144 CLASS="emphasis"
145 ><I
146 CLASS="EMPHASIS"
147 >Example:</I
148 ></SPAN
149 ></P
150 ><TABLE
151 BORDER="0"
152 BGCOLOR="#E0E0E0"
153 WIDTH="100%"
154 ><TR
155 ><TD
156 ><PRE
157 CLASS="PROGRAMLISTING"
158 >  /* if page size greater than 1k ... */
159   if (page_length() &#62; 1024)
160   {
161       ... "block" the page up ...
162   }
163
164   /* if page size is small, send it in blocks */
165   if (page_length() &#62; 1024)
166   {
167       ... "block" the page up ...
168   }
169
170   This demonstrates 2 cases of "what not to do".  The first is a
171   "syntax comment".  The second is a comment that does not fit what
172   is actually being done.</PRE
173 ></TD
174 ></TR
175 ></TABLE
176 ></DIV
177 ><DIV
178 CLASS="SECT3"
179 ><H3
180 CLASS="SECT3"
181 ><A
182 NAME="S4"
183 >4.2.2. Use blocks for comments</A
184 ></H3
185 ><P
186 ><SPAN
187 CLASS="emphasis"
188 ><I
189 CLASS="EMPHASIS"
190 >Explanation:</I
191 ></SPAN
192 ></P
193 ><P
194 >Comments can help or they can clutter. They help when they
195     are differentiated from the code they describe. One line
196     comments do not offer effective separation between the comment
197     and the code. Block identifiers do, by surrounding the code
198     with a clear, definable pattern.</P
199 ><P
200 ><SPAN
201 CLASS="emphasis"
202 ><I
203 CLASS="EMPHASIS"
204 >Example:</I
205 ></SPAN
206 ></P
207 ><TABLE
208 BORDER="0"
209 BGCOLOR="#E0E0E0"
210 WIDTH="100%"
211 ><TR
212 ><TD
213 ><PRE
214 CLASS="PROGRAMLISTING"
215 >  /*********************************************************************
216    * This will stand out clearly in your code!
217    *********************************************************************/
218   if (this_variable == that_variable)
219   {
220      do_something_very_important();
221   }
222
223
224   /* unfortunately, this may not */
225   if (this_variable == that_variable)
226   {
227      do_something_very_important();
228   }
229
230
231   if (this_variable == that_variable) /* this may not either */
232   {
233      do_something_very_important();
234   }</PRE
235 ></TD
236 ></TR
237 ></TABLE
238 ><P
239 ><SPAN
240 CLASS="emphasis"
241 ><I
242 CLASS="EMPHASIS"
243 >Exception:</I
244 ></SPAN
245 ></P
246 ><P
247 >If you are trying to add a small logic comment and do not
248     wish to "disrupt" the flow of the code, feel free to use a 1
249     line comment which is NOT on the same line as the code.</P
250 ></DIV
251 ><DIV
252 CLASS="SECT3"
253 ><H3
254 CLASS="SECT3"
255 ><A
256 NAME="S5"
257 >4.2.3. Keep Comments on their own line</A
258 ></H3
259 ><P
260 ><SPAN
261 CLASS="emphasis"
262 ><I
263 CLASS="EMPHASIS"
264 >Explanation:</I
265 ></SPAN
266 ></P
267 ><P
268 >It goes back to the question of readability. If the comment
269     is on the same line as the code it will be harder to read than
270     the comment that is on its own line.</P
271 ><P
272 >There are three exceptions to this rule, which should be
273     violated freely and often: during the definition of variables,
274     at the end of closing braces, when used to comment
275     parameters.</P
276 ><P
277 ><SPAN
278 CLASS="emphasis"
279 ><I
280 CLASS="EMPHASIS"
281 >Example:</I
282 ></SPAN
283 ></P
284 ><TABLE
285 BORDER="0"
286 BGCOLOR="#E0E0E0"
287 WIDTH="100%"
288 ><TR
289 ><TD
290 ><PRE
291 CLASS="PROGRAMLISTING"
292 >  /*********************************************************************
293    * This will stand out clearly in your code,
294    * But the second example won't.
295    *********************************************************************/
296   if (this_variable == this_variable)
297   {
298      do_something_very_important();
299   }
300
301   if (this_variable == this_variable) /*can you see me?*/
302   {
303      do_something_very_important(); /*not easily*/
304   }
305
306
307   /*********************************************************************
308    * But, the encouraged exceptions:
309    *********************************************************************/
310   int urls_read     = 0;     /* # of urls read + rejected */
311   int urls_rejected = 0;     /* # of urls rejected */
312
313   if (1 == X)
314   {
315      do_something_very_important();
316   }
317
318
319   short do_something_very_important(
320      short firstparam,   /* represents something */
321      short nextparam     /* represents something else */ )
322   {
323      ...code here...
324
325   }   /* -END- do_something_very_important */</PRE
326 ></TD
327 ></TR
328 ></TABLE
329 ></DIV
330 ><DIV
331 CLASS="SECT3"
332 ><H3
333 CLASS="SECT3"
334 ><A
335 NAME="S6"
336 >4.2.4. Comment each logical step</A
337 ></H3
338 ><P
339 ><SPAN
340 CLASS="emphasis"
341 ><I
342 CLASS="EMPHASIS"
343 >Explanation:</I
344 ></SPAN
345 ></P
346 ><P
347 >Logical steps should be commented to help others follow the
348     intent of the written code and comments will make the code more
349     readable.</P
350 ><P
351 >If you have 25 lines of code without a comment, you should
352     probably go back into it to see where you forgot to put
353     one.</P
354 ><P
355 >Most "for", "while", "do", etc... loops _probably_ need a
356     comment. After all, these are usually major logic
357     containers.</P
358 ></DIV
359 ><DIV
360 CLASS="SECT3"
361 ><H3
362 CLASS="SECT3"
363 ><A
364 NAME="S7"
365 >4.2.5. Comment All Functions Thoroughly</A
366 ></H3
367 ><P
368 ><SPAN
369 CLASS="emphasis"
370 ><I
371 CLASS="EMPHASIS"
372 >Explanation:</I
373 ></SPAN
374 ></P
375 ><P
376 >A reader of the code should be able to look at the comments
377     just prior to the beginning of a function and discern the
378     reason for its existence and the consequences of using it. The
379     reader should not have to read through the code to determine if
380     a given function is safe for a desired use. The proper
381     information thoroughly presented at the introduction of a
382     function not only saves time for subsequent maintenance or
383     debugging, it more importantly aids in code reuse by allowing a
384     user to determine the safety and applicability of any function
385     for the problem at hand. As a result of such benefits, all
386     functions should contain the information presented in the
387     addendum section of this document.</P
388 ></DIV
389 ><DIV
390 CLASS="SECT3"
391 ><H3
392 CLASS="SECT3"
393 ><A
394 NAME="S8"
395 >4.2.6. Comment at the end of braces if the
396     content is more than one screen length</A
397 ></H3
398 ><P
399 ><SPAN
400 CLASS="emphasis"
401 ><I
402 CLASS="EMPHASIS"
403 >Explanation:</I
404 ></SPAN
405 ></P
406 ><P
407 >Each closing brace should be followed on the same line by a
408     comment that describes the origination of the brace if the
409     original brace is off of the screen, or otherwise far away from
410     the closing brace. This will simplify the debugging,
411     maintenance, and readability of the code.</P
412 ><P
413 >As a suggestion , use the following flags to make the
414     comment and its brace more readable:</P
415 ><P
416 >use following a closing brace: } /* -END- if() or while ()
417     or etc... */</P
418 ><P
419 ><SPAN
420 CLASS="emphasis"
421 ><I
422 CLASS="EMPHASIS"
423 >Example:</I
424 ></SPAN
425 ></P
426 ><TABLE
427 BORDER="0"
428 BGCOLOR="#E0E0E0"
429 WIDTH="100%"
430 ><TR
431 ><TD
432 ><PRE
433 CLASS="PROGRAMLISTING"
434 >  if (1 == X)
435   {
436      do_something_very_important();
437      ...some long list of commands...
438   } /* -END- if x is 1 */
439
440   or:
441
442   if (1 == X)
443   {
444      do_something_very_important();
445      ...some long list of commands...
446   } /* -END- if (1 == X) */</PRE
447 ></TD
448 ></TR
449 ></TABLE
450 ></DIV
451 ></DIV
452 ><DIV
453 CLASS="SECT2"
454 ><H2
455 CLASS="SECT2"
456 ><A
457 NAME="S9"
458 >4.3. Naming Conventions</A
459 ></H2
460 ><DIV
461 CLASS="SECT3"
462 ><H3
463 CLASS="SECT3"
464 ><A
465 NAME="S10"
466 >4.3.1. Variable Names</A
467 ></H3
468 ><P
469 ><SPAN
470 CLASS="emphasis"
471 ><I
472 CLASS="EMPHASIS"
473 >Explanation:</I
474 ></SPAN
475 ></P
476 ><P
477 >Use all lowercase, and separate words via an underscore
478     ('_'). Do not start an identifier with an underscore. (ANSI C
479     reserves these for use by the compiler and system headers.) Do
480     not use identifiers which are reserved in ANSI C++. (E.g.
481     template, class, true, false, ...). This is in case we ever
482     decide to port Privoxy to C++.</P
483 ><P
484 ><SPAN
485 CLASS="emphasis"
486 ><I
487 CLASS="EMPHASIS"
488 >Example:</I
489 ></SPAN
490 ></P
491 ><TABLE
492 BORDER="0"
493 BGCOLOR="#E0E0E0"
494 WIDTH="100%"
495 ><TR
496 ><TD
497 ><PRE
498 CLASS="PROGRAMLISTING"
499 >  int ms_iis5_hack = 0;</PRE
500 ></TD
501 ></TR
502 ></TABLE
503 ><P
504 ><SPAN
505 CLASS="emphasis"
506 ><I
507 CLASS="EMPHASIS"
508 >Instead of:</I
509 ></SPAN
510 ></P
511 ><TABLE
512 BORDER="0"
513 BGCOLOR="#E0E0E0"
514 WIDTH="100%"
515 ><TR
516 ><TD
517 ><PRE
518 CLASS="PROGRAMLISTING"
519 >  int msiis5hack = 0; int msIis5Hack = 0;</PRE
520 ></TD
521 ></TR
522 ></TABLE
523 ></DIV
524 ><DIV
525 CLASS="SECT3"
526 ><H3
527 CLASS="SECT3"
528 ><A
529 NAME="S11"
530 >4.3.2. Function Names</A
531 ></H3
532 ><P
533 ><SPAN
534 CLASS="emphasis"
535 ><I
536 CLASS="EMPHASIS"
537 >Explanation:</I
538 ></SPAN
539 ></P
540 ><P
541 >Use all lowercase, and separate words via an underscore
542     ('_'). Do not start an identifier with an underscore. (ANSI C
543     reserves these for use by the compiler and system headers.) Do
544     not use identifiers which are reserved in ANSI C++. (E.g.
545     template, class, true, false, ...). This is in case we ever
546     decide to port Privoxy to C++.</P
547 ><P
548 ><SPAN
549 CLASS="emphasis"
550 ><I
551 CLASS="EMPHASIS"
552 >Example:</I
553 ></SPAN
554 ></P
555 ><TABLE
556 BORDER="0"
557 BGCOLOR="#E0E0E0"
558 WIDTH="100%"
559 ><TR
560 ><TD
561 ><PRE
562 CLASS="PROGRAMLISTING"
563 >  int load_some_file(struct client_state *csp)</PRE
564 ></TD
565 ></TR
566 ></TABLE
567 ><P
568 ><SPAN
569 CLASS="emphasis"
570 ><I
571 CLASS="EMPHASIS"
572 >Instead of:</I
573 ></SPAN
574 ></P
575 ><TABLE
576 BORDER="0"
577 BGCOLOR="#E0E0E0"
578 WIDTH="100%"
579 ><TR
580 ><TD
581 ><PRE
582 CLASS="PROGRAMLISTING"
583 >  int loadsomefile(struct client_state *csp)
584   int loadSomeFile(struct client_state *csp)</PRE
585 ></TD
586 ></TR
587 ></TABLE
588 ></DIV
589 ><DIV
590 CLASS="SECT3"
591 ><H3
592 CLASS="SECT3"
593 ><A
594 NAME="S12"
595 >4.3.3. Header file prototypes</A
596 ></H3
597 ><P
598 ><SPAN
599 CLASS="emphasis"
600 ><I
601 CLASS="EMPHASIS"
602 >Explanation:</I
603 ></SPAN
604 ></P
605 ><P
606 >Use a descriptive parameter name in the function prototype
607     in header files. Use the same parameter name in the header file
608     that you use in the c file.</P
609 ><P
610 ><SPAN
611 CLASS="emphasis"
612 ><I
613 CLASS="EMPHASIS"
614 >Example:</I
615 ></SPAN
616 ></P
617 ><TABLE
618 BORDER="0"
619 BGCOLOR="#E0E0E0"
620 WIDTH="100%"
621 ><TR
622 ><TD
623 ><PRE
624 CLASS="PROGRAMLISTING"
625 >  (.h) extern int load_aclfile(struct client_state *csp);
626   (.c) int load_aclfile(struct client_state *csp)</PRE
627 ></TD
628 ></TR
629 ></TABLE
630 ><P
631 ><SPAN
632 CLASS="emphasis"
633 ><I
634 CLASS="EMPHASIS"
635 >Instead of:</I
636 ></SPAN
637 ></P
638 ><TABLE
639 BORDER="0"
640 BGCOLOR="#E0E0E0"
641 WIDTH="100%"
642 ><TR
643 ><TD
644 ><PRE
645 CLASS="PROGRAMLISTING"
646 >  (.h) extern int load_aclfile(struct client_state *); or
647   (.h) extern int load_aclfile();
648   (.c) int load_aclfile(struct client_state *csp)</PRE
649 ></TD
650 ></TR
651 ></TABLE
652 ></DIV
653 ><DIV
654 CLASS="SECT3"
655 ><H3
656 CLASS="SECT3"
657 ><A
658 NAME="S13"
659 >4.3.4. Enumerations, and #defines</A
660 ></H3
661 ><P
662 ><SPAN
663 CLASS="emphasis"
664 ><I
665 CLASS="EMPHASIS"
666 >Explanation:</I
667 ></SPAN
668 ></P
669 ><P
670 >Use all capital letters, with underscores between words. Do
671     not start an identifier with an underscore. (ANSI C reserves
672     these for use by the compiler and system headers.)</P
673 ><P
674 ><SPAN
675 CLASS="emphasis"
676 ><I
677 CLASS="EMPHASIS"
678 >Example:</I
679 ></SPAN
680 ></P
681 ><TABLE
682 BORDER="0"
683 BGCOLOR="#E0E0E0"
684 WIDTH="100%"
685 ><TR
686 ><TD
687 ><PRE
688 CLASS="PROGRAMLISTING"
689 >  (enumeration) : enum Boolean {FALSE, TRUE};
690   (#define) : #define DEFAULT_SIZE 100;</PRE
691 ></TD
692 ></TR
693 ></TABLE
694 ><P
695 ><SPAN
696 CLASS="emphasis"
697 ><I
698 CLASS="EMPHASIS"
699 >Note:</I
700 ></SPAN
701 > We have a standard naming scheme for #defines
702     that toggle a feature in the preprocessor: FEATURE_&#62;, where
703     &#62; is a short (preferably 1 or 2 word) description.</P
704 ><P
705 ><SPAN
706 CLASS="emphasis"
707 ><I
708 CLASS="EMPHASIS"
709 >Example:</I
710 ></SPAN
711 ></P
712 ><TABLE
713 BORDER="0"
714 BGCOLOR="#E0E0E0"
715 WIDTH="100%"
716 ><TR
717 ><TD
718 ><PRE
719 CLASS="PROGRAMLISTING"
720 >  #define FEATURE_FORCE 1
721
722   #ifdef FEATURE_FORCE
723   #define FORCE_PREFIX blah
724   #endif /* def FEATURE_FORCE */</PRE
725 ></TD
726 ></TR
727 ></TABLE
728 ></DIV
729 ><DIV
730 CLASS="SECT3"
731 ><H3
732 CLASS="SECT3"
733 ><A
734 NAME="S14"
735 >4.3.5. Constants</A
736 ></H3
737 ><P
738 ><SPAN
739 CLASS="emphasis"
740 ><I
741 CLASS="EMPHASIS"
742 >Explanation:</I
743 ></SPAN
744 ></P
745 ><P
746 >Spell common words out entirely (do not remove vowels).</P
747 ><P
748 >Use only widely-known domain acronyms and abbreviations.
749     Capitalize all letters of an acronym.</P
750 ><P
751 >Use underscore (_) to separate adjacent acronyms and
752     abbreviations. Never terminate a name with an underscore.</P
753 ><P
754 ><SPAN
755 CLASS="emphasis"
756 ><I
757 CLASS="EMPHASIS"
758 >Example:</I
759 ></SPAN
760 ></P
761 ><TABLE
762 BORDER="0"
763 BGCOLOR="#E0E0E0"
764 WIDTH="100%"
765 ><TR
766 ><TD
767 ><PRE
768 CLASS="PROGRAMLISTING"
769 >  #define USE_IMAGE_LIST 1</PRE
770 ></TD
771 ></TR
772 ></TABLE
773 ><P
774 ><SPAN
775 CLASS="emphasis"
776 ><I
777 CLASS="EMPHASIS"
778 >Instead of:</I
779 ></SPAN
780 ></P
781 ><TABLE
782 BORDER="0"
783 BGCOLOR="#E0E0E0"
784 WIDTH="100%"
785 ><TR
786 ><TD
787 ><PRE
788 CLASS="PROGRAMLISTING"
789 >  #define USE_IMG_LST 1 or
790   #define _USE_IMAGE_LIST 1 or
791   #define USE_IMAGE_LIST_ 1 or
792   #define use_image_list 1 or
793   #define UseImageList 1</PRE
794 ></TD
795 ></TR
796 ></TABLE
797 ></DIV
798 ></DIV
799 ><DIV
800 CLASS="SECT2"
801 ><H2
802 CLASS="SECT2"
803 ><A
804 NAME="S15"
805 >4.4. Using Space</A
806 ></H2
807 ><DIV
808 CLASS="SECT3"
809 ><H3
810 CLASS="SECT3"
811 ><A
812 NAME="S16"
813 >4.4.1. Put braces on a line by themselves.</A
814 ></H3
815 ><P
816 ><SPAN
817 CLASS="emphasis"
818 ><I
819 CLASS="EMPHASIS"
820 >Explanation:</I
821 ></SPAN
822 ></P
823 ><P
824 >The brace needs to be on a line all by itself, not at the
825     end of the statement. Curly braces should line up with the
826     construct that they're associated with. This practice makes it
827     easier to identify the opening and closing braces for a
828     block.</P
829 ><P
830 ><SPAN
831 CLASS="emphasis"
832 ><I
833 CLASS="EMPHASIS"
834 >Example:</I
835 ></SPAN
836 ></P
837 ><TABLE
838 BORDER="0"
839 BGCOLOR="#E0E0E0"
840 WIDTH="100%"
841 ><TR
842 ><TD
843 ><PRE
844 CLASS="PROGRAMLISTING"
845 >  if (this == that)
846   {
847      ...
848   }</PRE
849 ></TD
850 ></TR
851 ></TABLE
852 ><P
853 ><SPAN
854 CLASS="emphasis"
855 ><I
856 CLASS="EMPHASIS"
857 >Instead of:</I
858 ></SPAN
859 ></P
860 ><P
861 >if (this == that) { ... }</P
862 ><P
863 >or</P
864 ><P
865 >if (this == that) { ... }</P
866 ><P
867 ><SPAN
868 CLASS="emphasis"
869 ><I
870 CLASS="EMPHASIS"
871 >Note:</I
872 ></SPAN
873 > In the special case that the if-statement is
874     inside a loop, and it is trivial, i.e. it tests for a
875     condition that is obvious from the purpose of the block,
876     one-liners as above may optically preserve the loop structure
877     and make it easier to read.</P
878 ><P
879 ><SPAN
880 CLASS="emphasis"
881 ><I
882 CLASS="EMPHASIS"
883 >Status:</I
884 ></SPAN
885 > developer-discretion.</P
886 ><P
887 ><SPAN
888 CLASS="emphasis"
889 ><I
890 CLASS="EMPHASIS"
891 >Example exception:</I
892 ></SPAN
893 ></P
894 ><TABLE
895 BORDER="0"
896 BGCOLOR="#E0E0E0"
897 WIDTH="100%"
898 ><TR
899 ><TD
900 ><PRE
901 CLASS="PROGRAMLISTING"
902 >  while (more lines are read)
903   {
904      /* Please document what is/is not a comment line here */
905      if (it's a comment) continue;
906
907      do_something(line);
908   }</PRE
909 ></TD
910 ></TR
911 ></TABLE
912 ></DIV
913 ><DIV
914 CLASS="SECT3"
915 ><H3
916 CLASS="SECT3"
917 ><A
918 NAME="S17"
919 >4.4.2. ALL control statements should have a
920     block</A
921 ></H3
922 ><P
923 ><SPAN
924 CLASS="emphasis"
925 ><I
926 CLASS="EMPHASIS"
927 >Explanation:</I
928 ></SPAN
929 ></P
930 ><P
931 >Using braces to make a block will make your code more
932     readable and less prone to error. All control statements should
933     have a block defined.</P
934 ><P
935 ><SPAN
936 CLASS="emphasis"
937 ><I
938 CLASS="EMPHASIS"
939 >Example:</I
940 ></SPAN
941 ></P
942 ><TABLE
943 BORDER="0"
944 BGCOLOR="#E0E0E0"
945 WIDTH="100%"
946 ><TR
947 ><TD
948 ><PRE
949 CLASS="PROGRAMLISTING"
950 >  if (this == that)
951   {
952      do_something();
953      do_something_else();
954   }</PRE
955 ></TD
956 ></TR
957 ></TABLE
958 ><P
959 ><SPAN
960 CLASS="emphasis"
961 ><I
962 CLASS="EMPHASIS"
963 >Instead of:</I
964 ></SPAN
965 ></P
966 ><P
967 >if (this == that) do_something(); do_something_else();</P
968 ><P
969 >or</P
970 ><P
971 >if (this == that) do_something();</P
972 ><P
973 ><SPAN
974 CLASS="emphasis"
975 ><I
976 CLASS="EMPHASIS"
977 >Note:</I
978 ></SPAN
979 > The first example in "Instead of" will execute
980     in a manner other than that which the developer desired (per
981     indentation). Using code braces would have prevented this
982     "feature". The "explanation" and "exception" from the point
983     above also applies.</P
984 ></DIV
985 ><DIV
986 CLASS="SECT3"
987 ><H3
988 CLASS="SECT3"
989 ><A
990 NAME="S18"
991 >4.4.3. Do not belabor/blow-up boolean
992     expressions</A
993 ></H3
994 ><P
995 ><SPAN
996 CLASS="emphasis"
997 ><I
998 CLASS="EMPHASIS"
999 >Example:</I
1000 ></SPAN
1001 ></P
1002 ><TABLE
1003 BORDER="0"
1004 BGCOLOR="#E0E0E0"
1005 WIDTH="100%"
1006 ><TR
1007 ><TD
1008 ><PRE
1009 CLASS="PROGRAMLISTING"
1010 >  structure-&#62;flag = (condition);</PRE
1011 ></TD
1012 ></TR
1013 ></TABLE
1014 ><P
1015 ><SPAN
1016 CLASS="emphasis"
1017 ><I
1018 CLASS="EMPHASIS"
1019 >Instead of:</I
1020 ></SPAN
1021 ></P
1022 ><P
1023 >if (condition) { structure-&#62;flag = 1; } else {
1024     structure-&#62;flag = 0; }</P
1025 ><P
1026 ><SPAN
1027 CLASS="emphasis"
1028 ><I
1029 CLASS="EMPHASIS"
1030 >Note:</I
1031 ></SPAN
1032 > The former is readable and concise. The later
1033     is wordy and inefficient. Please assume that any developer new
1034     to the project has at least a "good" knowledge of C/C++. (Hope
1035     I do not offend by that last comment ... 8-)</P
1036 ></DIV
1037 ><DIV
1038 CLASS="SECT3"
1039 ><H3
1040 CLASS="SECT3"
1041 ><A
1042 NAME="S19"
1043 >4.4.4. Use white space freely because it is
1044     free</A
1045 ></H3
1046 ><P
1047 ><SPAN
1048 CLASS="emphasis"
1049 ><I
1050 CLASS="EMPHASIS"
1051 >Explanation:</I
1052 ></SPAN
1053 ></P
1054 ><P
1055 >Make it readable. The notable exception to using white space
1056     freely is listed in the next guideline.</P
1057 ><P
1058 ><SPAN
1059 CLASS="emphasis"
1060 ><I
1061 CLASS="EMPHASIS"
1062 >Example:</I
1063 ></SPAN
1064 ></P
1065 ><TABLE
1066 BORDER="0"
1067 BGCOLOR="#E0E0E0"
1068 WIDTH="100%"
1069 ><TR
1070 ><TD
1071 ><PRE
1072 CLASS="PROGRAMLISTING"
1073 >  int first_value   = 0;
1074   int some_value    = 0;
1075   int another_value = 0;
1076   int this_variable = 0;</PRE
1077 ></TD
1078 ></TR
1079 ></TABLE
1080 ></DIV
1081 ><DIV
1082 CLASS="SECT3"
1083 ><H3
1084 CLASS="SECT3"
1085 ><A
1086 NAME="S20"
1087 >4.4.5. Don't use white space around structure
1088     operators</A
1089 ></H3
1090 ><P
1091 ><SPAN
1092 CLASS="emphasis"
1093 ><I
1094 CLASS="EMPHASIS"
1095 >Explanation:</I
1096 ></SPAN
1097 ></P
1098 ><P
1099 >- structure pointer operator ( "-&#62;" ) - member operator (
1100     "." ) - functions and parentheses</P
1101 ><P
1102 >It is a general coding practice to put pointers, references,
1103     and function parentheses next to names. With spaces, the
1104     connection between the object and variable/function name is not
1105     as clear.</P
1106 ><P
1107 ><SPAN
1108 CLASS="emphasis"
1109 ><I
1110 CLASS="EMPHASIS"
1111 >Example:</I
1112 ></SPAN
1113 ></P
1114 ><TABLE
1115 BORDER="0"
1116 BGCOLOR="#E0E0E0"
1117 WIDTH="100%"
1118 ><TR
1119 ><TD
1120 ><PRE
1121 CLASS="PROGRAMLISTING"
1122 >  a_struct-&#62;a_member;
1123   a_struct.a_member;
1124   function_name();</PRE
1125 ></TD
1126 ></TR
1127 ></TABLE
1128 ><P
1129 ><SPAN
1130 CLASS="emphasis"
1131 ><I
1132 CLASS="EMPHASIS"
1133 >Instead of:</I
1134 ></SPAN
1135 > a_struct -&#62; a_member; a_struct . a_member;
1136     function_name ();</P
1137 ></DIV
1138 ><DIV
1139 CLASS="SECT3"
1140 ><H3
1141 CLASS="SECT3"
1142 ><A
1143 NAME="S21"
1144 >4.4.6. Make the last brace of a function stand
1145     out</A
1146 ></H3
1147 ><P
1148 ><SPAN
1149 CLASS="emphasis"
1150 ><I
1151 CLASS="EMPHASIS"
1152 >Example:</I
1153 ></SPAN
1154 ></P
1155 ><TABLE
1156 BORDER="0"
1157 BGCOLOR="#E0E0E0"
1158 WIDTH="100%"
1159 ><TR
1160 ><TD
1161 ><PRE
1162 CLASS="PROGRAMLISTING"
1163 >  int function1( ... )
1164   {
1165      ...code...
1166      return(ret_code);
1167
1168   } /* -END- function1 */
1169
1170
1171   int function2( ... )
1172   {
1173   } /* -END- function2 */</PRE
1174 ></TD
1175 ></TR
1176 ></TABLE
1177 ><P
1178 ><SPAN
1179 CLASS="emphasis"
1180 ><I
1181 CLASS="EMPHASIS"
1182 >Instead of:</I
1183 ></SPAN
1184 ></P
1185 ><P
1186 >int function1( ... ) { ...code... return(ret_code); } int
1187     function2( ... ) { }</P
1188 ><P
1189 ><SPAN
1190 CLASS="emphasis"
1191 ><I
1192 CLASS="EMPHASIS"
1193 >Note:</I
1194 ></SPAN
1195 > Use 1 blank line before the closing brace and 2
1196     lines afterward. This makes the end of function standout to
1197     the most casual viewer. Although function comments help
1198     separate functions, this is still a good coding practice. In
1199     fact, I follow these rules when using blocks in "for", "while",
1200     "do" loops, and long if {} statements too. After all whitespace
1201     is free!</P
1202 ><P
1203 ><SPAN
1204 CLASS="emphasis"
1205 ><I
1206 CLASS="EMPHASIS"
1207 >Status:</I
1208 ></SPAN
1209 > developer-discretion on the number of blank
1210     lines. Enforced is the end of function comments.</P
1211 ></DIV
1212 ><DIV
1213 CLASS="SECT3"
1214 ><H3
1215 CLASS="SECT3"
1216 ><A
1217 NAME="S22"
1218 >4.4.7. Use 3 character indentions</A
1219 ></H3
1220 ><P
1221 ><SPAN
1222 CLASS="emphasis"
1223 ><I
1224 CLASS="EMPHASIS"
1225 >Explanation:</I
1226 ></SPAN
1227 ></P
1228 ><P
1229 >If some use 8 character TABs and some use 3 character TABs,
1230     the code can look *very* ragged. So use 3 character indentions
1231     only. If you like to use TABs, pass your code through a filter
1232     such as "expand -t3" before checking in your code.</P
1233 ><P
1234 ><SPAN
1235 CLASS="emphasis"
1236 ><I
1237 CLASS="EMPHASIS"
1238 >Example:</I
1239 ></SPAN
1240 ></P
1241 ><TABLE
1242 BORDER="0"
1243 BGCOLOR="#E0E0E0"
1244 WIDTH="100%"
1245 ><TR
1246 ><TD
1247 ><PRE
1248 CLASS="PROGRAMLISTING"
1249 >  static const char * const url_code_map[256] =
1250   {
1251      NULL, ...
1252   };
1253
1254
1255   int function1( ... )
1256   {
1257      if (1)
1258      {
1259         return ALWAYS_TRUE;
1260      }
1261      else
1262      {
1263         return HOW_DID_YOU_GET_HERE;
1264      }
1265
1266      return NEVER_GETS_HERE;
1267
1268   }</PRE
1269 ></TD
1270 ></TR
1271 ></TABLE
1272 ></DIV
1273 ></DIV
1274 ><DIV
1275 CLASS="SECT2"
1276 ><H2
1277 CLASS="SECT2"
1278 ><A
1279 NAME="S23"
1280 >4.5. Initializing</A
1281 ></H2
1282 ><DIV
1283 CLASS="SECT3"
1284 ><H3
1285 CLASS="SECT3"
1286 ><A
1287 NAME="S24"
1288 >4.5.1. Initialize all variables</A
1289 ></H3
1290 ><P
1291 ><SPAN
1292 CLASS="emphasis"
1293 ><I
1294 CLASS="EMPHASIS"
1295 >Explanation:</I
1296 ></SPAN
1297 ></P
1298 ><P
1299 >Do not assume that the variables declared will not be used
1300     until after they have been assigned a value somewhere else in
1301     the code. Remove the chance of accidentally using an unassigned
1302     variable.</P
1303 ><P
1304 ><SPAN
1305 CLASS="emphasis"
1306 ><I
1307 CLASS="EMPHASIS"
1308 >Example:</I
1309 ></SPAN
1310 ></P
1311 ><TABLE
1312 BORDER="0"
1313 BGCOLOR="#E0E0E0"
1314 WIDTH="100%"
1315 ><TR
1316 ><TD
1317 ><PRE
1318 CLASS="PROGRAMLISTING"
1319 >  short a_short = 0;
1320   float a_float  = 0;
1321   struct *ptr = NULL;</PRE
1322 ></TD
1323 ></TR
1324 ></TABLE
1325 ><P
1326 ><SPAN
1327 CLASS="emphasis"
1328 ><I
1329 CLASS="EMPHASIS"
1330 >Note:</I
1331 ></SPAN
1332 > It is much easier to debug a SIGSEGV if the
1333     message says you are trying to access memory address 00000000
1334     and not 129FA012; or array_ptr[20] causes a SIGSEV vs.
1335     array_ptr[0].</P
1336 ><P
1337 ><SPAN
1338 CLASS="emphasis"
1339 ><I
1340 CLASS="EMPHASIS"
1341 >Status:</I
1342 ></SPAN
1343 > developer-discretion if and only if the
1344     variable is assigned a value "shortly after" declaration.</P
1345 ></DIV
1346 ></DIV
1347 ><DIV
1348 CLASS="SECT2"
1349 ><H2
1350 CLASS="SECT2"
1351 ><A
1352 NAME="S25"
1353 >4.6. Functions</A
1354 ></H2
1355 ><DIV
1356 CLASS="SECT3"
1357 ><H3
1358 CLASS="SECT3"
1359 ><A
1360 NAME="S26"
1361 >4.6.1. Name functions that return a boolean as a
1362     question.</A
1363 ></H3
1364 ><P
1365 ><SPAN
1366 CLASS="emphasis"
1367 ><I
1368 CLASS="EMPHASIS"
1369 >Explanation:</I
1370 ></SPAN
1371 ></P
1372 ><P
1373 >Value should be phrased as a question that would logically
1374     be answered as a true or false statement</P
1375 ><P
1376 ><SPAN
1377 CLASS="emphasis"
1378 ><I
1379 CLASS="EMPHASIS"
1380 >Example:</I
1381 ></SPAN
1382 ></P
1383 ><TABLE
1384 BORDER="0"
1385 BGCOLOR="#E0E0E0"
1386 WIDTH="100%"
1387 ><TR
1388 ><TD
1389 ><PRE
1390 CLASS="PROGRAMLISTING"
1391 >  should_we_block_this();
1392   contains_an_image();
1393   is_web_page_blank();</PRE
1394 ></TD
1395 ></TR
1396 ></TABLE
1397 ></DIV
1398 ><DIV
1399 CLASS="SECT3"
1400 ><H3
1401 CLASS="SECT3"
1402 ><A
1403 NAME="S27"
1404 >4.6.2. Always specify a return type for a
1405     function.</A
1406 ></H3
1407 ><P
1408 ><SPAN
1409 CLASS="emphasis"
1410 ><I
1411 CLASS="EMPHASIS"
1412 >Explanation:</I
1413 ></SPAN
1414 ></P
1415 ><P
1416 >The default return for a function is an int. To avoid
1417     ambiguity, create a return for a function when the return has a
1418     purpose, and create a void return type if the function does not
1419     need to return anything.</P
1420 ></DIV
1421 ><DIV
1422 CLASS="SECT3"
1423 ><H3
1424 CLASS="SECT3"
1425 ><A
1426 NAME="S28"
1427 >4.6.3. Minimize function calls when iterating by
1428     using variables</A
1429 ></H3
1430 ><P
1431 ><SPAN
1432 CLASS="emphasis"
1433 ><I
1434 CLASS="EMPHASIS"
1435 >Explanation:</I
1436 ></SPAN
1437 ></P
1438 ><P
1439 >It is easy to write the following code, and a clear argument
1440     can be made that the code is easy to understand:</P
1441 ><P
1442 ><SPAN
1443 CLASS="emphasis"
1444 ><I
1445 CLASS="EMPHASIS"
1446 >Example:</I
1447 ></SPAN
1448 ></P
1449 ><TABLE
1450 BORDER="0"
1451 BGCOLOR="#E0E0E0"
1452 WIDTH="100%"
1453 ><TR
1454 ><TD
1455 ><PRE
1456 CLASS="PROGRAMLISTING"
1457 >  for (size_t cnt = 0; cnt &lt; block_list_length(); cnt++)
1458   {
1459      ....
1460   }</PRE
1461 ></TD
1462 ></TR
1463 ></TABLE
1464 ><P
1465 ><SPAN
1466 CLASS="emphasis"
1467 ><I
1468 CLASS="EMPHASIS"
1469 >Note:</I
1470 ></SPAN
1471 > Unfortunately, this makes a function call for
1472     each and every iteration. This increases the overhead in the
1473     program, because the compiler has to look up the function each
1474     time, call it, and return a value. Depending on what occurs in
1475     the block_list_length() call, it might even be creating and
1476     destroying structures with each iteration, even though in each
1477     case it is comparing "cnt" to the same value, over and over.
1478     Remember too - even a call to block_list_length() is a function
1479     call, with the same overhead.</P
1480 ><P
1481 >Instead of using a function call during the iterations,
1482     assign the value to a variable, and evaluate using the
1483     variable.</P
1484 ><P
1485 ><SPAN
1486 CLASS="emphasis"
1487 ><I
1488 CLASS="EMPHASIS"
1489 >Example:</I
1490 ></SPAN
1491 ></P
1492 ><TABLE
1493 BORDER="0"
1494 BGCOLOR="#E0E0E0"
1495 WIDTH="100%"
1496 ><TR
1497 ><TD
1498 ><PRE
1499 CLASS="PROGRAMLISTING"
1500 >  size_t len = block_list_length();
1501
1502   for (size_t cnt = 0; cnt &lt; len; cnt++)
1503   {
1504      ....
1505   }</PRE
1506 ></TD
1507 ></TR
1508 ></TABLE
1509 ><P
1510 ><SPAN
1511 CLASS="emphasis"
1512 ><I
1513 CLASS="EMPHASIS"
1514 >Exceptions:</I
1515 ></SPAN
1516 > if the value of block_list_length()
1517     *may* change or could *potentially* change, then you must code the
1518     function call in the for/while loop.</P
1519 ></DIV
1520 ><DIV
1521 CLASS="SECT3"
1522 ><H3
1523 CLASS="SECT3"
1524 ><A
1525 NAME="S29"
1526 >4.6.4. Pass and Return by Const Reference</A
1527 ></H3
1528 ><P
1529 ><SPAN
1530 CLASS="emphasis"
1531 ><I
1532 CLASS="EMPHASIS"
1533 >Explanation:</I
1534 ></SPAN
1535 ></P
1536 ><P
1537 >This allows a developer to define a const pointer and call
1538     your function. If your function does not have the const
1539     keyword, we may not be able to use your function. Consider
1540     strcmp, if it were defined as: extern int strcmp(char *s1,
1541     char *s2);</P
1542 ><P
1543 >I could then not use it to compare argv's in main: int
1544     main(int argc, const char *argv[]) { strcmp(argv[0], "privoxy");
1545      }</P
1546 ><P
1547 >Both these pointers are *const*! If the c runtime library
1548     maintainers do it, we should too.</P
1549 ></DIV
1550 ><DIV
1551 CLASS="SECT3"
1552 ><H3
1553 CLASS="SECT3"
1554 ><A
1555 NAME="S30"
1556 >4.6.5. Pass and Return by Value</A
1557 ></H3
1558 ><P
1559 ><SPAN
1560 CLASS="emphasis"
1561 ><I
1562 CLASS="EMPHASIS"
1563 >Explanation:</I
1564 ></SPAN
1565 ></P
1566 ><P
1567 >Most structures cannot fit onto a normal stack entry (i.e.
1568     they are not 4 bytes or less). Aka, a function declaration
1569     like: int load_aclfile(struct client_state csp)</P
1570 ><P
1571 >would not work. So, to be consistent, we should declare all
1572     prototypes with "pass by value": int load_aclfile(struct
1573     client_state *csp)</P
1574 ></DIV
1575 ><DIV
1576 CLASS="SECT3"
1577 ><H3
1578 CLASS="SECT3"
1579 ><A
1580 NAME="S31"
1581 >4.6.6. Names of include files</A
1582 ></H3
1583 ><P
1584 ><SPAN
1585 CLASS="emphasis"
1586 ><I
1587 CLASS="EMPHASIS"
1588 >Explanation:</I
1589 ></SPAN
1590 ></P
1591 ><P
1592 >Your include statements should contain the file name without
1593     a path. The path should be listed in the Makefile, using -I as
1594     processor directive to search the indicated paths. An exception
1595     to this would be for some proprietary software that utilizes a
1596     partial path to distinguish their header files from system or
1597     other header files.</P
1598 ><P
1599 ><SPAN
1600 CLASS="emphasis"
1601 ><I
1602 CLASS="EMPHASIS"
1603 >Example:</I
1604 ></SPAN
1605 ></P
1606 ><TABLE
1607 BORDER="0"
1608 BGCOLOR="#E0E0E0"
1609 WIDTH="100%"
1610 ><TR
1611 ><TD
1612 ><PRE
1613 CLASS="PROGRAMLISTING"
1614 >  #include &lt;iostream.h&gt;     /* This is not a local include */
1615   #include "config.h"       /* This IS a local include */</PRE
1616 ></TD
1617 ></TR
1618 ></TABLE
1619 ><P
1620 ><SPAN
1621 CLASS="emphasis"
1622 ><I
1623 CLASS="EMPHASIS"
1624 >Exception:</I
1625 ></SPAN
1626 ></P
1627 ><TABLE
1628 BORDER="0"
1629 BGCOLOR="#E0E0E0"
1630 WIDTH="100%"
1631 ><TR
1632 ><TD
1633 ><PRE
1634 CLASS="PROGRAMLISTING"
1635 >  /* This is not a local include, but requires a path element. */
1636   #include &lt;sys/fileName.h&gt;</PRE
1637 ></TD
1638 ></TR
1639 ></TABLE
1640 ><P
1641 ><SPAN
1642 CLASS="emphasis"
1643 ><I
1644 CLASS="EMPHASIS"
1645 >Note:</I
1646 ></SPAN
1647 > Please! do not add "-I." to the Makefile
1648     without a _very_ good reason. This duplicates the #include
1649     "file.h" behavior.</P
1650 ></DIV
1651 ><DIV
1652 CLASS="SECT3"
1653 ><H3
1654 CLASS="SECT3"
1655 ><A
1656 NAME="S32"
1657 >4.6.7. Provide multiple inclusion
1658     protection</A
1659 ></H3
1660 ><P
1661 ><SPAN
1662 CLASS="emphasis"
1663 ><I
1664 CLASS="EMPHASIS"
1665 >Explanation:</I
1666 ></SPAN
1667 ></P
1668 ><P
1669 >Prevents compiler and linker errors resulting from
1670     redefinition of items.</P
1671 ><P
1672 >Wrap each header file with the following syntax to prevent
1673     multiple inclusions of the file. Of course, replace PROJECT_H
1674     with your file name, with "." Changed to "_", and make it
1675     uppercase.</P
1676 ><P
1677 ><SPAN
1678 CLASS="emphasis"
1679 ><I
1680 CLASS="EMPHASIS"
1681 >Example:</I
1682 ></SPAN
1683 ></P
1684 ><TABLE
1685 BORDER="0"
1686 BGCOLOR="#E0E0E0"
1687 WIDTH="100%"
1688 ><TR
1689 ><TD
1690 ><PRE
1691 CLASS="PROGRAMLISTING"
1692 >  #ifndef PROJECT_H_INCLUDED
1693   #define PROJECT_H_INCLUDED
1694    ...
1695   #endif /* ndef PROJECT_H_INCLUDED */</PRE
1696 ></TD
1697 ></TR
1698 ></TABLE
1699 ></DIV
1700 ><DIV
1701 CLASS="SECT3"
1702 ><H3
1703 CLASS="SECT3"
1704 ><A
1705 NAME="S33"
1706 >4.6.8. Use `extern "C"` when appropriate</A
1707 ></H3
1708 ><P
1709 ><SPAN
1710 CLASS="emphasis"
1711 ><I
1712 CLASS="EMPHASIS"
1713 >Explanation:</I
1714 ></SPAN
1715 ></P
1716 ><P
1717 >If our headers are included from C++, they must declare our
1718     functions as `extern "C"`. This has no cost in C, but increases
1719     the potential re-usability of our code.</P
1720 ><P
1721 ><SPAN
1722 CLASS="emphasis"
1723 ><I
1724 CLASS="EMPHASIS"
1725 >Example:</I
1726 ></SPAN
1727 ></P
1728 ><TABLE
1729 BORDER="0"
1730 BGCOLOR="#E0E0E0"
1731 WIDTH="100%"
1732 ><TR
1733 ><TD
1734 ><PRE
1735 CLASS="PROGRAMLISTING"
1736 >  #ifdef __cplusplus
1737   extern "C"
1738   {
1739   #endif /* def __cplusplus */
1740
1741   ... function definitions here ...
1742
1743   #ifdef __cplusplus
1744   }
1745   #endif /* def __cplusplus */</PRE
1746 ></TD
1747 ></TR
1748 ></TABLE
1749 ></DIV
1750 ><DIV
1751 CLASS="SECT3"
1752 ><H3
1753 CLASS="SECT3"
1754 ><A
1755 NAME="S34"
1756 >4.6.9. Where Possible, Use Forward Struct
1757     Declaration Instead of Includes</A
1758 ></H3
1759 ><P
1760 ><SPAN
1761 CLASS="emphasis"
1762 ><I
1763 CLASS="EMPHASIS"
1764 >Explanation:</I
1765 ></SPAN
1766 ></P
1767 ><P
1768 >Useful in headers that include pointers to other struct's.
1769     Modifications to excess header files may cause needless
1770     compiles.</P
1771 ><P
1772 ><SPAN
1773 CLASS="emphasis"
1774 ><I
1775 CLASS="EMPHASIS"
1776 >Example:</I
1777 ></SPAN
1778 ></P
1779 ><TABLE
1780 BORDER="0"
1781 BGCOLOR="#E0E0E0"
1782 WIDTH="100%"
1783 ><TR
1784 ><TD
1785 ><PRE
1786 CLASS="PROGRAMLISTING"
1787 >  /*********************************************************************
1788    * We're avoiding an include statement here!
1789    *********************************************************************/
1790   struct file_list;
1791   extern file_list *xyz;</PRE
1792 ></TD
1793 ></TR
1794 ></TABLE
1795 ><P
1796 ><SPAN
1797 CLASS="emphasis"
1798 ><I
1799 CLASS="EMPHASIS"
1800 >Note:</I
1801 ></SPAN
1802 > If you declare "file_list xyz;" (without the
1803     pointer), then including the proper header file is necessary.
1804     If you only want to prototype a pointer, however, the header
1805     file is unnecessary.</P
1806 ><P
1807 ><SPAN
1808 CLASS="emphasis"
1809 ><I
1810 CLASS="EMPHASIS"
1811 >Status:</I
1812 ></SPAN
1813 > Use with discretion.</P
1814 ></DIV
1815 ></DIV
1816 ><DIV
1817 CLASS="SECT2"
1818 ><H2
1819 CLASS="SECT2"
1820 ><A
1821 NAME="S35"
1822 >4.7. General Coding Practices</A
1823 ></H2
1824 ><DIV
1825 CLASS="SECT3"
1826 ><H3
1827 CLASS="SECT3"
1828 ><A
1829 NAME="S36"
1830 >4.7.1. Turn on warnings</A
1831 ></H3
1832 ><P
1833 ><SPAN
1834 CLASS="emphasis"
1835 ><I
1836 CLASS="EMPHASIS"
1837 >Explanation</I
1838 ></SPAN
1839 ></P
1840 ><P
1841 >Compiler warnings are meant to help you find bugs. You
1842     should turn on as many as possible. With GCC, the switch is
1843     "-Wall". Try and fix as many warnings as possible.</P
1844 ></DIV
1845 ><DIV
1846 CLASS="SECT3"
1847 ><H3
1848 CLASS="SECT3"
1849 ><A
1850 NAME="S37"
1851 >4.7.2. Provide a default case for all switch
1852     statements</A
1853 ></H3
1854 ><P
1855 ><SPAN
1856 CLASS="emphasis"
1857 ><I
1858 CLASS="EMPHASIS"
1859 >Explanation:</I
1860 ></SPAN
1861 ></P
1862 ><P
1863 >What you think is guaranteed is never really guaranteed. The
1864     value that you don't think you need to check is the one that
1865     someday will be passed. So, to protect yourself from the
1866     unknown, always have a default step in a switch statement.</P
1867 ><P
1868 ><SPAN
1869 CLASS="emphasis"
1870 ><I
1871 CLASS="EMPHASIS"
1872 >Example:</I
1873 ></SPAN
1874 ></P
1875 ><TABLE
1876 BORDER="0"
1877 BGCOLOR="#E0E0E0"
1878 WIDTH="100%"
1879 ><TR
1880 ><TD
1881 ><PRE
1882 CLASS="PROGRAMLISTING"
1883 >  switch (hash_string(cmd))
1884   {
1885      case hash_actions_file:
1886         ... code ...
1887         break;
1888
1889      case hash_confdir:
1890         ... code ...
1891         break;
1892
1893      default:
1894         log_error( ... );
1895         ... anomaly code goes here ...
1896         continue; / break; / exit( 1 ); / etc ...
1897
1898   } /* end switch (hash_string(cmd)) */</PRE
1899 ></TD
1900 ></TR
1901 ></TABLE
1902 ><P
1903 ><SPAN
1904 CLASS="emphasis"
1905 ><I
1906 CLASS="EMPHASIS"
1907 >Note:</I
1908 ></SPAN
1909 > If you already have a default condition, you
1910     are obviously exempt from this point. Of note, most of the
1911     WIN32 code calls `DefWindowProc' after the switch statement.
1912     This API call *should* be included in a default statement.</P
1913 ><P
1914 ><SPAN
1915 CLASS="emphasis"
1916 ><I
1917 CLASS="EMPHASIS"
1918 >Another Note:</I
1919 ></SPAN
1920 > This is not so much a readability issue
1921     as a robust programming issue. The "anomaly code goes here" may
1922     be no more than a print to the STDERR stream (as in
1923     load_config). Or it may really be an abort condition.</P
1924 ><P
1925 ><SPAN
1926 CLASS="emphasis"
1927 ><I
1928 CLASS="EMPHASIS"
1929 >Status:</I
1930 ></SPAN
1931 > Programmer discretion is advised.</P
1932 ></DIV
1933 ><DIV
1934 CLASS="SECT3"
1935 ><H3
1936 CLASS="SECT3"
1937 ><A
1938 NAME="S38"
1939 >4.7.3. Try to avoid falling through cases in a
1940     switch statement.</A
1941 ></H3
1942 ><P
1943 ><SPAN
1944 CLASS="emphasis"
1945 ><I
1946 CLASS="EMPHASIS"
1947 >Explanation:</I
1948 ></SPAN
1949 ></P
1950 ><P
1951 >In general, you will want to have a 'break' statement within
1952     each 'case' of a switch statement. This allows for the code to
1953     be more readable and understandable, and furthermore can
1954     prevent unwanted surprises if someone else later gets creative
1955     and moves the code around.</P
1956 ><P
1957 >The language allows you to plan the fall through from one
1958     case statement to another simply by omitting the break
1959     statement within the case statement. This feature does have
1960     benefits, but should only be used in rare cases. In general,
1961     use a break statement for each case statement.</P
1962 ><P
1963 >If you choose to allow fall through, you should comment both
1964     the fact of the fall through and reason why you felt it was
1965     necessary.</P
1966 ></DIV
1967 ><DIV
1968 CLASS="SECT3"
1969 ><H3
1970 CLASS="SECT3"
1971 ><A
1972 NAME="S40"
1973 >4.7.4. Don't mix size_t and other types</A
1974 ></H3
1975 ><P
1976 ><SPAN
1977 CLASS="emphasis"
1978 ><I
1979 CLASS="EMPHASIS"
1980 >Explanation:</I
1981 ></SPAN
1982 ></P
1983 ><P
1984 >The type of size_t varies across platforms. Do not make
1985     assumptions about whether it is signed or unsigned, or about
1986     how long it is. Do not compare a size_t against another
1987     variable of a different type (or even against a constant)
1988     without casting one of the values.</P
1989 ></DIV
1990 ><DIV
1991 CLASS="SECT3"
1992 ><H3
1993 CLASS="SECT3"
1994 ><A
1995 NAME="S41"
1996 >4.7.5. Declare each variable and struct on its
1997     own line.</A
1998 ></H3
1999 ><P
2000 ><SPAN
2001 CLASS="emphasis"
2002 ><I
2003 CLASS="EMPHASIS"
2004 >Explanation:</I
2005 ></SPAN
2006 ></P
2007 ><P
2008 >It can be tempting to declare a series of variables all on
2009     one line. Don't.</P
2010 ><P
2011 ><SPAN
2012 CLASS="emphasis"
2013 ><I
2014 CLASS="EMPHASIS"
2015 >Example:</I
2016 ></SPAN
2017 ></P
2018 ><TABLE
2019 BORDER="0"
2020 BGCOLOR="#E0E0E0"
2021 WIDTH="100%"
2022 ><TR
2023 ><TD
2024 ><PRE
2025 CLASS="PROGRAMLISTING"
2026 >  long a = 0;
2027   long b = 0;
2028   long c = 0;</PRE
2029 ></TD
2030 ></TR
2031 ></TABLE
2032 ><P
2033 ><SPAN
2034 CLASS="emphasis"
2035 ><I
2036 CLASS="EMPHASIS"
2037 >Instead of:</I
2038 ></SPAN
2039 ></P
2040 ><P
2041 >long a, b, c;</P
2042 ><P
2043 ><SPAN
2044 CLASS="emphasis"
2045 ><I
2046 CLASS="EMPHASIS"
2047 >Explanation:</I
2048 ></SPAN
2049 > - there is more room for comments on the
2050     individual variables - easier to add new variables without
2051     messing up the original ones - when searching on a variable to
2052     find its type, there is less clutter to "visually"
2053     eliminate</P
2054 ><P
2055 ><SPAN
2056 CLASS="emphasis"
2057 ><I
2058 CLASS="EMPHASIS"
2059 >Exceptions:</I
2060 ></SPAN
2061 > when you want to declare a bunch of loop
2062     variables or other trivial variables; feel free to declare them
2063     on one line. You should, although, provide a good comment on
2064     their functions.</P
2065 ><P
2066 ><SPAN
2067 CLASS="emphasis"
2068 ><I
2069 CLASS="EMPHASIS"
2070 >Status:</I
2071 ></SPAN
2072 > developer-discretion.</P
2073 ></DIV
2074 ><DIV
2075 CLASS="SECT3"
2076 ><H3
2077 CLASS="SECT3"
2078 ><A
2079 NAME="S42"
2080 >4.7.6. Use malloc/zalloc sparingly</A
2081 ></H3
2082 ><P
2083 ><SPAN
2084 CLASS="emphasis"
2085 ><I
2086 CLASS="EMPHASIS"
2087 >Explanation:</I
2088 ></SPAN
2089 ></P
2090 ><P
2091 >Create a local struct (on the stack) if the variable will
2092     live and die within the context of one function call.</P
2093 ><P
2094 >Only "malloc" a struct (on the heap) if the variable's life
2095     will extend beyond the context of one function call.</P
2096 ><P
2097 ><SPAN
2098 CLASS="emphasis"
2099 ><I
2100 CLASS="EMPHASIS"
2101 >Example:</I
2102 ></SPAN
2103 ></P
2104 ><TABLE
2105 BORDER="0"
2106 BGCOLOR="#E0E0E0"
2107 WIDTH="100%"
2108 ><TR
2109 ><TD
2110 ><PRE
2111 CLASS="PROGRAMLISTING"
2112 >  If a function creates a struct and stores a pointer to it in a
2113   list, then it should definitely be allocated via `malloc'.</PRE
2114 ></TD
2115 ></TR
2116 ></TABLE
2117 ></DIV
2118 ><DIV
2119 CLASS="SECT3"
2120 ><H3
2121 CLASS="SECT3"
2122 ><A
2123 NAME="S43"
2124 >4.7.7. The Programmer Who Uses 'malloc' is
2125     Responsible for Ensuring 'free'</A
2126 ></H3
2127 ><P
2128 ><SPAN
2129 CLASS="emphasis"
2130 ><I
2131 CLASS="EMPHASIS"
2132 >Explanation:</I
2133 ></SPAN
2134 ></P
2135 ><P
2136 >If you have to "malloc" an instance, you are responsible for
2137     insuring that the instance is `free'd, even if the deallocation
2138     event falls within some other programmer's code. You are also
2139     responsible for ensuring that deletion is timely (i.e. not too
2140     soon, not too late). This is known as "low-coupling" and is a
2141     "good thing (tm)". You may need to offer a
2142     free/unload/destructor type function to accommodate this.</P
2143 ><P
2144 ><SPAN
2145 CLASS="emphasis"
2146 ><I
2147 CLASS="EMPHASIS"
2148 >Example:</I
2149 ></SPAN
2150 ></P
2151 ><TABLE
2152 BORDER="0"
2153 BGCOLOR="#E0E0E0"
2154 WIDTH="100%"
2155 ><TR
2156 ><TD
2157 ><PRE
2158 CLASS="PROGRAMLISTING"
2159 >  int load_re_filterfile(struct client_state *csp) { ... }
2160   static void unload_re_filterfile(void *f) { ... }</PRE
2161 ></TD
2162 ></TR
2163 ></TABLE
2164 ><P
2165 ><SPAN
2166 CLASS="emphasis"
2167 ><I
2168 CLASS="EMPHASIS"
2169 >Exceptions:</I
2170 ></SPAN
2171 ></P
2172 ><P
2173 >The developer cannot be expected to provide `free'ing
2174     functions for C run-time library functions ... such as
2175     `strdup'.</P
2176 ><P
2177 ><SPAN
2178 CLASS="emphasis"
2179 ><I
2180 CLASS="EMPHASIS"
2181 >Status:</I
2182 ></SPAN
2183 > developer-discretion. The "main" use of this
2184     standard is for allocating and freeing data structures (complex
2185     or nested).</P
2186 ></DIV
2187 ><DIV
2188 CLASS="SECT3"
2189 ><H3
2190 CLASS="SECT3"
2191 ><A
2192 NAME="S44"
2193 >4.7.8. Add loaders to the `file_list' structure
2194     and in order</A
2195 ></H3
2196 ><P
2197 ><SPAN
2198 CLASS="emphasis"
2199 ><I
2200 CLASS="EMPHASIS"
2201 >Explanation:</I
2202 ></SPAN
2203 ></P
2204 ><P
2205 >I have ordered all of the "blocker" file code to be in alpha
2206     order. It is easier to add/read new blockers when you expect a
2207     certain order.</P
2208 ><P
2209 ><SPAN
2210 CLASS="emphasis"
2211 ><I
2212 CLASS="EMPHASIS"
2213 >Note:</I
2214 ></SPAN
2215 > It may appear that the alpha order is broken in
2216     places by POPUP tests coming before PCRS tests. But since
2217     POPUPs can also be referred to as KILLPOPUPs, it is clear that
2218     it should come first.</P
2219 ></DIV
2220 ><DIV
2221 CLASS="SECT3"
2222 ><H3
2223 CLASS="SECT3"
2224 ><A
2225 NAME="S45"
2226 >4.7.9. "Uncertain" new code and/or changes to
2227     existing code, use XXX</A
2228 ></H3
2229 ><P
2230 ><SPAN
2231 CLASS="emphasis"
2232 ><I
2233 CLASS="EMPHASIS"
2234 >Explanation:</I
2235 ></SPAN
2236 ></P
2237 ><P
2238 >If you have enough confidence in new code or confidence in
2239     your changes, but are not *quite* sure of the repercussions,
2240     add this:</P
2241 ><P
2242 >/* XXX: this code has a logic error on platform XYZ, *
2243     attempting to fix */ #ifdef PLATFORM ...changed code here...
2244     #endif</P
2245 ><P
2246 >or:</P
2247 ><P
2248 >/* XXX: I think the original author really meant this...
2249     */ ...changed code here...</P
2250 ><P
2251 >or:</P
2252 ><P
2253 >/* XXX: new code that *may* break something else... */
2254     ...new code here...</P
2255 ><P
2256 ><SPAN
2257 CLASS="emphasis"
2258 ><I
2259 CLASS="EMPHASIS"
2260 >Note:</I
2261 ></SPAN
2262 > If you make it clear that this may or may not
2263     be a "good thing (tm)", it will be easier to identify and
2264     include in the project (or conversely exclude from the
2265     project).</P
2266 ></DIV
2267 ></DIV
2268 ><DIV
2269 CLASS="SECT2"
2270 ><H2
2271 CLASS="SECT2"
2272 ><A
2273 NAME="S46"
2274 >4.8. Addendum: Template for files and function
2275     comment blocks:</A
2276 ></H2
2277 ><P
2278 ><SPAN
2279 CLASS="emphasis"
2280 ><I
2281 CLASS="EMPHASIS"
2282 >Example for file comments:</I
2283 ></SPAN
2284 ></P
2285 ><TABLE
2286 BORDER="0"
2287 BGCOLOR="#E0E0E0"
2288 WIDTH="100%"
2289 ><TR
2290 ><TD
2291 ><PRE
2292 CLASS="PROGRAMLISTING"
2293 >  /*********************************************************************
2294    *
2295    * File        :  $Source
2296    *
2297    * Purpose     :  (Fill me in with a good description!)
2298    *
2299    * Copyright   :  Written by and Copyright (C) 2001-2009
2300    *                the Privoxy team. https://www.privoxy.org/
2301    *
2302    *                This program is free software; you can redistribute it
2303    *                and/or modify it under the terms of the GNU General
2304    *                Public License as published by the Free Software
2305    *                Foundation; either version 2 of the License, or (at
2306    *                your option) any later version.
2307    *
2308    *                This program is distributed in the hope that it will
2309    *                be useful, but WITHOUT ANY WARRANTY; without even the
2310    *                implied warranty of MERCHANTABILITY or FITNESS FOR A
2311    *                PARTICULAR PURPOSE.  See the GNU General Public
2312    *                License for more details.
2313    *
2314    *                The GNU General Public License should be included with
2315    *                this file.  If not, you can view it at
2316    *                http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
2317    *                or write to the Free Software Foundation, Inc.,
2318    *                51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
2319    *                USA
2320    *
2321    *********************************************************************/
2322
2323
2324   #include "config.h"
2325
2326      ...necessary include files for us to do our work...
2327
2328   const char FILENAME_h_rcs[] = FILENAME_H_VERSION;</PRE
2329 ></TD
2330 ></TR
2331 ></TABLE
2332 ><P
2333 ><SPAN
2334 CLASS="emphasis"
2335 ><I
2336 CLASS="EMPHASIS"
2337 >Note:</I
2338 ></SPAN
2339 > This declares the rcs variables that should be
2340     added to the "show-version" page. If this is a brand new
2341     creation by you, you are free to change the "Copyright" section
2342     to represent the rights you wish to maintain.</P
2343 ><P
2344 ><SPAN
2345 CLASS="emphasis"
2346 ><I
2347 CLASS="EMPHASIS"
2348 >Note:</I
2349 ></SPAN
2350 > The formfeed character that is present right
2351     after the comment flower box is handy for (X|GNU)Emacs users to
2352     skip the verbiage and get to the heart of the code (via
2353     `forward-page' and `backward-page'). Please include it if you
2354     can.</P
2355 ><P
2356 ><SPAN
2357 CLASS="emphasis"
2358 ><I
2359 CLASS="EMPHASIS"
2360 >Example for file header comments:</I
2361 ></SPAN
2362 ></P
2363 ><TABLE
2364 BORDER="0"
2365 BGCOLOR="#E0E0E0"
2366 WIDTH="100%"
2367 ><TR
2368 ><TD
2369 ><PRE
2370 CLASS="PROGRAMLISTING"
2371 >  #ifndef _FILENAME_H
2372   #define _FILENAME_H
2373   /*********************************************************************
2374    *
2375    * File        :  $Source
2376    *
2377    * Purpose     :  (Fill me in with a good description!)
2378    *
2379    * Copyright   :  Written by and Copyright (C) 2001-2009
2380    *                the Privoxy team. https://www.privoxy.org/
2381    *
2382    *                This program is free software; you can redistribute it
2383    *                and/or modify it under the terms of the GNU General
2384    *                Public License as published by the Free Software
2385    *                Foundation; either version 2 of the License, or (at
2386    *                your option) any later version.
2387    *
2388    *                This program is distributed in the hope that it will
2389    *                be useful, but WITHOUT ANY WARRANTY; without even the
2390    *                implied warranty of MERCHANTABILITY or FITNESS FOR A
2391    *                PARTICULAR PURPOSE.  See the GNU General Public
2392    *                License for more details.
2393    *
2394    *                The GNU General Public License should be included with
2395    *                this file.  If not, you can view it at
2396    *                http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
2397    *                or write to the Free Software Foundation, Inc.,
2398    *                51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
2399    *                USA
2400    *
2401    *********************************************************************/
2402
2403
2404   #include "project.h"
2405
2406   #ifdef __cplusplus
2407   extern "C" {
2408   #endif
2409
2410      ... function headers here ...
2411
2412
2413   /* Revision control strings from this header and associated .c file */
2414   extern const char FILENAME_rcs[];
2415   extern const char FILENAME_h_rcs[];
2416
2417
2418   #ifdef __cplusplus
2419   } /* extern "C" */
2420   #endif
2421
2422   #endif /* ndef _FILENAME_H */
2423
2424   /*
2425     Local Variables:
2426     tab-width: 3
2427     end:
2428   */</PRE
2429 ></TD
2430 ></TR
2431 ></TABLE
2432 ><P
2433 ><SPAN
2434 CLASS="emphasis"
2435 ><I
2436 CLASS="EMPHASIS"
2437 >Example for function comments:</I
2438 ></SPAN
2439 ></P
2440 ><TABLE
2441 BORDER="0"
2442 BGCOLOR="#E0E0E0"
2443 WIDTH="100%"
2444 ><TR
2445 ><TD
2446 ><PRE
2447 CLASS="PROGRAMLISTING"
2448 >  /*********************************************************************
2449    *
2450    * Function    :  FUNCTION_NAME
2451    *
2452    * Description :  (Fill me in with a good description!)
2453    *
2454    * parameters  :
2455    *          1  :  param1 = pointer to an important thing
2456    *          2  :  x      = pointer to something else
2457    *
2458    * Returns     :  0 =&#62; Ok, everything else is an error.
2459    *
2460    *********************************************************************/
2461   int FUNCTION_NAME(void *param1, const char *x)
2462   {
2463      ...
2464      return 0;
2465
2466   }</PRE
2467 ></TD
2468 ></TR
2469 ></TABLE
2470 ><P
2471 ><SPAN
2472 CLASS="emphasis"
2473 ><I
2474 CLASS="EMPHASIS"
2475 >Note:</I
2476 ></SPAN
2477 > If we all follow this practice, we should be
2478     able to parse our code to create a "self-documenting" web
2479     page.</P
2480 ></DIV
2481 ></DIV
2482 ><DIV
2483 CLASS="NAVFOOTER"
2484 ><HR
2485 ALIGN="LEFT"
2486 WIDTH="100%"><TABLE
2487 SUMMARY="Footer navigation table"
2488 WIDTH="100%"
2489 BORDER="0"
2490 CELLPADDING="0"
2491 CELLSPACING="0"
2492 ><TR
2493 ><TD
2494 WIDTH="33%"
2495 ALIGN="left"
2496 VALIGN="top"
2497 ><A
2498 HREF="documentation.html"
2499 ACCESSKEY="P"
2500 >Prev</A
2501 ></TD
2502 ><TD
2503 WIDTH="34%"
2504 ALIGN="center"
2505 VALIGN="top"
2506 ><A
2507 HREF="index.html"
2508 ACCESSKEY="H"
2509 >Home</A
2510 ></TD
2511 ><TD
2512 WIDTH="33%"
2513 ALIGN="right"
2514 VALIGN="top"
2515 ><A
2516 HREF="testing.html"
2517 ACCESSKEY="N"
2518 >Next</A
2519 ></TD
2520 ></TR
2521 ><TR
2522 ><TD
2523 WIDTH="33%"
2524 ALIGN="left"
2525 VALIGN="top"
2526 >Documentation Guidelines</TD
2527 ><TD
2528 WIDTH="34%"
2529 ALIGN="center"
2530 VALIGN="top"
2531 >&nbsp;</TD
2532 ><TD
2533 WIDTH="33%"
2534 ALIGN="right"
2535 VALIGN="top"
2536 >Testing Guidelines</TD
2537 ></TR
2538 ></TABLE
2539 ></DIV
2540 ></BODY
2541 ></HTML
2542 >