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.txt). |
---|
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. |
---|