The Psychology of Quality and More

C Style: Standards and Guidelines (contents)

CHAPTER 7 : File Layout

PART 3 : LAYOUT

CHAPTER 7 : File Layout
7.1 Layout of directories
7.2 Division of files
7.3 Considerations for File Layout
7.4 Header files
7.5 Layout of Data files
7.6 Layout of Code files
7.7 Summary

<--Prev page | Next page -->

7.5  Layout of Data files

When a number of functions, spread across several files, refer directly to a global data object, where should that object be defined? If it is not 'owned' by any single file, then the answer is to put it in a global data file.

7.5.1  Division and layout of data files

The division and layout of data files should broadly follow the rules for header files. Thus a typical format might be:

   File heading comment

   Identification/copyright string

   Include files

   Common context items:

       #define's, enum's

   Functional area 1:

       Heading comment

       #define's, enum's for context

       Data definition 1:

                   Heading comment

                   #define's, enum's for context

                   typedef or struct to define data item

       Data definition 2:

          ...

   Functional area 2:

   ...

7.5.2  Header files and data files

Declaring the context within the data file may cause problems where that context is also required within the code that references the data. One way of avoiding duplicate declarations is to put the external references to the data in a header file, created from a copy of the data file (thus simply ensuring that they match):

/* kbddata.h */
#define KB_BUF_LEN  256                  /* context for KbdBuffer     */
extern  char    KbdBuffer[KB_BUF_LEN];   /* duplicate from kbddata.c  */

/* kbddata.c */
#include "kbddata.h"                     /* use context                */
char    KbdBuffer[KB_BUF_LEN];           /* definition of global data  */

/* kbdio.c */
#include "kbddata.h"                     /* include context and extern */
...
for ( i = 0; i < KB_BUF_LEN; i++ )       /* use context                */
    KbdBuffer[i] = ' ';                  /* use global data            */

--------------------------------------------------------------------------

Having to keep two sets of data like this may cause maintenance problems, although the inclusion of the header file containing the extern in the data file will cause the compiler to flag any inconsistencies. An alternative is to use the preprocessor to make the header file dual purpose:

/* kbddata.h */
#ifndef GLOBAL
#define GLOBAL extern
#endif
#define KB_BUF_LEN  256                  /* context for KbdBuffer      */
GLOBAL  char    KbdBuffer[KB_BUF_LEN];   /* definition if GLOBAL def'd */

/* kbddata.c */
#define GLOBAL                           /* force data definition      */
#include "kbddata.h"                     /* this is the entire file!   */

/* kbdio.c */
#include "kbddata.h"                     /* context and externs        */
...

<--Prev page | Next page -->