28C. Naming and Documenting Structure Types

Choosing field and type names

---

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

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. If a field is a count of the number of edges, call it numEdges, not edges or edge.

Documenting structure types

---

The standards for this course require each structure type to be documented. Say

1. what an object of the given structure 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. 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;
  };

A complete documentation would also document constructors. For this course, you are not required to do that. But be sure that your documentation of the structure type is not actually documentation of its constructor(s).