24B. Naming and Documentation of Structures


Choosing field and type names

The standards require you to choose sensible type and field names. An object that is one cell should have type Cell, not type Cells. An object that represents a mountain should have type Mountain, not River and not Stuff.

Some illustrations in these notes use single-letter field names to keep things short. But field names tend to be used over a large part of a program, and they should be descriptive. If a field is an edge, call it anEdge rather than e. You can probably choose an even better name than that.


Documenting structure types

The standards require each structure type to be documented. Say

  1. what an object of the given type represents, and

  2. what property of the object each field in the structure represents.

When documenting a field, it is not enough to say what its type is. In fact, telling the type is pointless; that is obvious from the type definition. Say what information the field represents or how the field is used.

For example, here is a possible description of type Road.

  // An object of type Road represents a road.
  // The fields are:
  //
  //    name	the name of the road, such as "I90".
  //
  //    length  the total length of the road in miles.
  //
  //    year    the year when the road construction was
  //            completed.

  struct Road
  {
    const char* name;
    double      length;
    int         year;
  };