This document is a result of a committee formed at Indian Hill to establish a common set of coding standards and recommendations for the Indian Hill community. The scope of this work is the coding style, not the functional organization of programs. The standards in this document are not specific to ESS programming only. We have tried to combine previous work on C style into a uniform set of standards that should be appropriate for any project using C.
A file consists of various sections that should be separated by several blank lines. Although there is no maximum length requirement for source files, files with more than about 1500 lines are cumbersome to deal with. The editor may not have enough temp space to edit the file, compilations will go slower, etc. Since most of us use 300 baud terminals, entire rows of asterisks, for example, should be discouraged. Also lines longer than 80 columns are not handled well by all terminals and should be avoided if possible.
The suggested order of sections for a file is as follows:
- Any header file includes should be the first thing in the file.
- Immediately after the includes should be a prologue that tells what is in that file. A description of the purpose of the objects in the files (whether they be functions, external data declarations or definitions, or something else) is more useful than a list of the object names.
- Any typedefs and defines that apply to the file as a whole are next.
- Next come the global (external) data declarations. If a set of defines applies to a particular piece of global data (such as a flags word), the defines should be immediately after the data declaration.
- The functions come last.
File Naming Conventions
Unix requires certain suffix conventions for names of files to be processed by the cc command. The following suffixes are required:
- C source file names must end in .c
- Assembler source file names must end in .s
In addition the following conventions are universally followed:
- Relocatable object file names end in .o
- Include header file names end in .h or .d
- Ldp specification file names end in .b
- Yacc source file names end in .y
- Lex source file names end in .l
- Header Files
Header files are files that are included in other files prior to compilation by the C preprocessor. Some are defined at the system level like stdio.h which must be included by any program using the standard I/O library. Header files are also used to contain data declarations and defines that are needed by more than one program. Header files should be functionally organized, i.e., declarations for separate subsystems should be in separate header files. Also, if a set of declarations is likely to change when code is ported from one machine to another, those declarations should be in a separate header file.
Header files should not be nested. Some objects like typedefs and initialized data definitions cannot be seen twice by the compiler in one compilation. On non-Unix systems this is also true of uninitialized declarations without the extern keyword. This can happen if include files are nested and will cause the compilation to fail.