123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778 |
- IJG JPEG LIBRARY: CODING RULES
- This file was part of the Independent JPEG Group's software:
- Copyright (C) 1991-1996, Thomas G. Lane.
- It was modified by The libjpeg-turbo Project to include only information
- relevant to libjpeg-turbo.
- For conditions of distribution and use, see the accompanying README.ijg file.
- Since numerous people will be contributing code and bug fixes, it's important
- to establish a common coding style. The goal of using similar coding styles
- is much more important than the details of just what that style is.
- In general we follow the recommendations of "Recommended C Style and Coding
- Standards" revision 6.1 (Cannon et al. as modified by Spencer, Keppel and
- Brader). This document is available in the IJG FTP archive (see
- jpeg/doc/cstyle.ms.tbl.Z, or cstyle.txt.Z for those without nroff/tbl).
- Block comments should be laid out thusly:
- /*
- * Block comments in this style.
- */
- We indent statements in K&R style, e.g.,
- if (test) {
- then-part;
- } else {
- else-part;
- }
- with two spaces per indentation level. (This indentation convention is
- handled automatically by GNU Emacs and many other text editors.)
- Multi-word names should be written in lower case with underscores, e.g.,
- multi_word_name (not multiWordName). Preprocessor symbols and enum constants
- are similar but upper case (MULTI_WORD_NAME). Names should be unique within
- the first fifteen characters.
- Note that each function definition must begin with GLOBAL(type), LOCAL(type),
- or METHODDEF(type). These macros expand to "static type" or just "type" as
- appropriate. They provide a readable indication of the routine's usage and
- can readily be changed for special needs. (For instance, special linkage
- keywords can be inserted for use in Windows DLLs.)
- A similar solution is used for external function declarations (see the EXTERN
- macro.)
- The JPEG library is intended to be used within larger programs. Furthermore,
- we want it to be reentrant so that it can be used by applications that process
- multiple images concurrently. The following rules support these requirements:
- 1. Avoid direct use of file I/O, "malloc", error report printouts, etc;
- pass these through the common routines provided.
- 2. Minimize global namespace pollution. Functions should be declared static
- wherever possible. (Note that our method-based calling conventions help this
- a lot: in many modules only the initialization function will ever need to be
- called directly, so only that function need be externally visible.) All
- global function names should begin with "jpeg_".
- 3. Don't use global variables; anything that must be used in another module
- should be in the common data structures.
- 4. Don't use static variables except for read-only constant tables. Variables
- that should be private to a module can be placed into private structures (see
- the system architecture document, structure.txt).
- 5. Source file names should begin with "j" for files that are part of the
- library proper; source files that are not part of the library, such as cjpeg.c
- and djpeg.c, do not begin with "j". Keep compression and decompression code in
- separate source files --- some applications may want only one half of the
- library.
- Note: these rules (particularly #4) are not followed religiously in the
- modules that are used in cjpeg/djpeg but are not part of the JPEG library
- proper. Those modules are not really intended to be used in other
- applications.
|