Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1 | IJG JPEG LIBRARY: CODING RULES |
| 2 | |
DRC | 5033f3e | 2014-05-18 18:33:44 +0000 | [diff] [blame] | 3 | This file was part of the Independent JPEG Group's software: |
Thomas G. Lane | 489583f | 1996-02-07 00:00:00 +0000 | [diff] [blame] | 4 | Copyright (C) 1991-1996, Thomas G. Lane. |
DRC | bc56b75 | 2014-05-16 10:43:44 +0000 | [diff] [blame] | 5 | It was modified by The libjpeg-turbo Project to include only information |
| 6 | relevant to libjpeg-turbo. |
DRC | 7e3acc0 | 2015-10-10 10:25:46 -0500 | [diff] [blame^] | 7 | For conditions of distribution and use, see the accompanying README.ijg file. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 8 | |
| 9 | |
| 10 | Since numerous people will be contributing code and bug fixes, it's important |
| 11 | to establish a common coding style. The goal of using similar coding styles |
| 12 | is much more important than the details of just what that style is. |
| 13 | |
| 14 | In general we follow the recommendations of "Recommended C Style and Coding |
| 15 | Standards" revision 6.1 (Cannon et al. as modified by Spencer, Keppel and |
| 16 | Brader). This document is available in the IJG FTP archive (see |
| 17 | jpeg/doc/cstyle.ms.tbl.Z, or cstyle.txt.Z for those without nroff/tbl). |
| 18 | |
| 19 | Block comments should be laid out thusly: |
| 20 | |
| 21 | /* |
| 22 | * Block comments in this style. |
| 23 | */ |
| 24 | |
| 25 | We indent statements in K&R style, e.g., |
DRC | e5eaf37 | 2014-05-09 18:00:32 +0000 | [diff] [blame] | 26 | if (test) { |
| 27 | then-part; |
| 28 | } else { |
| 29 | else-part; |
| 30 | } |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 31 | with two spaces per indentation level. (This indentation convention is |
| 32 | handled automatically by GNU Emacs and many other text editors.) |
| 33 | |
| 34 | Multi-word names should be written in lower case with underscores, e.g., |
| 35 | multi_word_name (not multiWordName). Preprocessor symbols and enum constants |
| 36 | are similar but upper case (MULTI_WORD_NAME). Names should be unique within |
DRC | bc56b75 | 2014-05-16 10:43:44 +0000 | [diff] [blame] | 37 | the first fifteen characters. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 38 | |
Thomas G. Lane | 489583f | 1996-02-07 00:00:00 +0000 | [diff] [blame] | 39 | Note that each function definition must begin with GLOBAL(type), LOCAL(type), |
| 40 | or METHODDEF(type). These macros expand to "static type" or just "type" as |
| 41 | appropriate. They provide a readable indication of the routine's usage and |
| 42 | can readily be changed for special needs. (For instance, special linkage |
| 43 | keywords can be inserted for use in Windows DLLs.) |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 44 | |
DRC | bc56b75 | 2014-05-16 10:43:44 +0000 | [diff] [blame] | 45 | A similar solution is used for external function declarations (see the EXTERN |
| 46 | macro.) |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 47 | |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 48 | |
| 49 | The JPEG library is intended to be used within larger programs. Furthermore, |
| 50 | we want it to be reentrant so that it can be used by applications that process |
| 51 | multiple images concurrently. The following rules support these requirements: |
| 52 | |
| 53 | 1. Avoid direct use of file I/O, "malloc", error report printouts, etc; |
| 54 | pass these through the common routines provided. |
| 55 | |
| 56 | 2. Minimize global namespace pollution. Functions should be declared static |
| 57 | wherever possible. (Note that our method-based calling conventions help this |
| 58 | a lot: in many modules only the initialization function will ever need to be |
| 59 | called directly, so only that function need be externally visible.) All |
DRC | 52ded87 | 2014-05-15 20:30:16 +0000 | [diff] [blame] | 60 | global function names should begin with "jpeg_". |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 61 | |
| 62 | 3. Don't use global variables; anything that must be used in another module |
| 63 | should be in the common data structures. |
| 64 | |
| 65 | 4. Don't use static variables except for read-only constant tables. Variables |
| 66 | that should be private to a module can be placed into private structures (see |
Guido Vollbeding | 5996a25 | 2009-06-27 00:00:00 +0000 | [diff] [blame] | 67 | the system architecture document, structure.txt). |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 68 | |
| 69 | 5. Source file names should begin with "j" for files that are part of the |
| 70 | library proper; source files that are not part of the library, such as cjpeg.c |
DRC | bc56b75 | 2014-05-16 10:43:44 +0000 | [diff] [blame] | 71 | and djpeg.c, do not begin with "j". Keep compression and decompression code in |
| 72 | separate source files --- some applications may want only one half of the |
| 73 | library. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 74 | |
| 75 | Note: these rules (particularly #4) are not followed religiously in the |
| 76 | modules that are used in cjpeg/djpeg but are not part of the JPEG library |
| 77 | proper. Those modules are not really intended to be used in other |
| 78 | applications. |