1 IJG JPEG LIBRARY: CODING RULES |
|
2 |
|
3 Copyright (C) 1991-1996, Thomas G. Lane. |
|
4 This file is part of the Independent JPEG Group's software. |
|
5 For conditions of distribution and use, see the accompanying README file. |
|
6 |
|
7 |
|
8 Since numerous people will be contributing code and bug fixes, it's important |
|
9 to establish a common coding style. The goal of using similar coding styles |
|
10 is much more important than the details of just what that style is. |
|
11 |
|
12 In general we follow the recommendations of "Recommended C Style and Coding |
|
13 Standards" revision 6.1 (Cannon et al. as modified by Spencer, Keppel and |
|
14 Brader). This document is available in the IJG FTP archive (see |
|
15 jpeg/doc/cstyle.ms.tbl.Z, or cstyle.txt.Z for those without nroff/tbl). |
|
16 |
|
17 Block comments should be laid out thusly: |
|
18 |
|
19 /* |
|
20 * Block comments in this style. |
|
21 */ |
|
22 |
|
23 We indent statements in K&R style, e.g., |
|
24 if (test) { |
|
25 then-part; |
|
26 } else { |
|
27 else-part; |
|
28 } |
|
29 with two spaces per indentation level. (This indentation convention is |
|
30 handled automatically by GNU Emacs and many other text editors.) |
|
31 |
|
32 Multi-word names should be written in lower case with underscores, e.g., |
|
33 multi_word_name (not multiWordName). Preprocessor symbols and enum constants |
|
34 are similar but upper case (MULTI_WORD_NAME). Names should be unique within |
|
35 the first fifteen characters. (On some older systems, global names must be |
|
36 unique within six characters. We accommodate this without cluttering the |
|
37 source code by using macros to substitute shorter names.) |
|
38 |
|
39 We use function prototypes everywhere; we rely on automatic source code |
|
40 transformation to feed prototype-less C compilers. Transformation is done |
|
41 by the simple and portable tool 'ansi2knr.c' (courtesy of Ghostscript). |
|
42 ansi2knr is not very bright, so it imposes a format requirement on function |
|
43 declarations: the function name MUST BEGIN IN COLUMN 1. Thus all functions |
|
44 should be written in the following style: |
|
45 |
|
46 LOCAL(int *) |
|
47 function_name (int a, char *b) |
|
48 { |
|
49 code... |
|
50 } |
|
51 |
|
52 Note that each function definition must begin with GLOBAL(type), LOCAL(type), |
|
53 or METHODDEF(type). These macros expand to "static type" or just "type" as |
|
54 appropriate. They provide a readable indication of the routine's usage and |
|
55 can readily be changed for special needs. (For instance, special linkage |
|
56 keywords can be inserted for use in Windows DLLs.) |
|
57 |
|
58 ansi2knr does not transform method declarations (function pointers in |
|
59 structs). We handle these with a macro JMETHOD, defined as |
|
60 #ifdef HAVE_PROTOTYPES |
|
61 #define JMETHOD(type,methodname,arglist) type (*methodname) arglist |
|
62 #else |
|
63 #define JMETHOD(type,methodname,arglist) type (*methodname) () |
|
64 #endif |
|
65 which is used like this: |
|
66 struct function_pointers { |
|
67 JMETHOD(void, init_entropy_encoder, (int somearg, jparms *jp)); |
|
68 JMETHOD(void, term_entropy_encoder, (void)); |
|
69 }; |
|
70 Note the set of parentheses surrounding the parameter list. |
|
71 |
|
72 A similar solution is used for forward and external function declarations |
|
73 (see the EXTERN and JPP macros). |
|
74 |
|
75 If the code is to work on non-ANSI compilers, we cannot rely on a prototype |
|
76 declaration to coerce actual parameters into the right types. Therefore, use |
|
77 explicit casts on actual parameters whenever the actual parameter type is not |
|
78 identical to the formal parameter. Beware of implicit conversions to "int". |
|
79 |
|
80 It seems there are some non-ANSI compilers in which the sizeof() operator |
|
81 is defined to return int, yet size_t is defined as long. Needless to say, |
|
82 this is brain-damaged. Always use the SIZEOF() macro in place of sizeof(), |
|
83 so that the result is guaranteed to be of type size_t. |
|
84 |
|
85 |
|
86 The JPEG library is intended to be used within larger programs. Furthermore, |
|
87 we want it to be reentrant so that it can be used by applications that process |
|
88 multiple images concurrently. The following rules support these requirements: |
|
89 |
|
90 1. Avoid direct use of file I/O, "malloc", error report printouts, etc; |
|
91 pass these through the common routines provided. |
|
92 |
|
93 2. Minimize global namespace pollution. Functions should be declared static |
|
94 wherever possible. (Note that our method-based calling conventions help this |
|
95 a lot: in many modules only the initialization function will ever need to be |
|
96 called directly, so only that function need be externally visible.) All |
|
97 global function names should begin with "jpeg_", and should have an |
|
98 abbreviated name (unique in the first six characters) substituted by macro |
|
99 when NEED_SHORT_EXTERNAL_NAMES is set. |
|
100 |
|
101 3. Don't use global variables; anything that must be used in another module |
|
102 should be in the common data structures. |
|
103 |
|
104 4. Don't use static variables except for read-only constant tables. Variables |
|
105 that should be private to a module can be placed into private structures (see |
|
106 the system architecture document, structure.doc). |
|
107 |
|
108 5. Source file names should begin with "j" for files that are part of the |
|
109 library proper; source files that are not part of the library, such as cjpeg.c |
|
110 and djpeg.c, do not begin with "j". Keep source file names to eight |
|
111 characters (plus ".c" or ".h", etc) to make life easy for MS-DOSers. Keep |
|
112 compression and decompression code in separate source files --- some |
|
113 applications may want only one half of the library. |
|
114 |
|
115 Note: these rules (particularly #4) are not followed religiously in the |
|
116 modules that are used in cjpeg/djpeg but are not part of the JPEG library |
|
117 proper. Those modules are not really intended to be used in other |
|
118 applications. |
|