Writing Code for the Next Person
File Description
It is good practice to describe code files at the top of the file. This helps avoid wasted time looking at the contents of code files that are not really the subject of what one is trying to accomplish. The file description should also be an aid to those wanting to use the file, making it much faster to understand the purpose of the code, usage, etc.
The following is an example of a template I use for all of my projects.
/*
* MODULE_NAME
*
* Copyright (C) 2025
* All Rights Reserved
*
* Author:
* Paul E. Jones <paulej@packetizer.com>
*
* Description:
* DESCRIPTION
*
* Portability Issues:
* None.
*/
I use this style of template in every source file I create. I put in the name of the file at the top ("MODULE_NAME") and enter a brief description in te "DESCRIPTION" area. The description should explain why the file exists. More specifically, it should explain what functions, classes, or definitions in a file do broadly. Don't put details here that should be in function-level descriptions. Rather, put in text that tells the reader what the file is about.
For C++ header files, I generally provide enough information to enable the developer to start using a class (or classes) without even looking further into the header and definitely not the corresponding source file(s). This helps with both coming up to speed on source files, as well as code reuse.
For C++ implementation files, I will generally detail anything that might not be obvious from reading the comments in the .h file. I treat the "DESCRIPTION" in a .h file as "public information anyone using this class should know" and the "DESCRIPTION" in the .cpp file as "private information anyone modifying this source file should know."
This separation does not really map to many other languages, but an appropriate file-level description is nonetheless valuable in every language I have used.
The following is a real example of a RingBuffer class that I wrote. In this case, one can guess from the name of the file what it is about. However, I felt that there were a few things worth noting to prospective users of this class that aid in determining whether this might be some useful code.
/*
* ring_buffer.h
*
* Copyright (C) 2025
* All Rights Reserved
*
* Author:
* Paul E. Jones <paulej@packetizer.com>
*
* Description:
* This file a defines a RingBuffer object that allows one to insert and
* retrieve elements of a given type into and from a ring buffer of a
* predetermined size. This RingBuffer is written using C++ template
* syntax, thus allowing the type of elements to be any type that can
* have default construction.
*
* When the RingBuffer is full and an attempt is made to insert new data,
* the behavior can be either to throw an exception when the RingBugger is
* full (default) or to overwrite the oldest data. Overwriting is
* controlled by the EnableOverwriting() call. This mode is useful, for
* example, when receiving data packets over a network where the items left
* in a buffer for too long are considered stale and should be discarded as
* newer packets arrive.
*
* Portability Issues:
* None.
*/
One may add additional sections as appropriate. In general, limiting the sections to a few, consistent sections is best. Consistency aids in faster human consumption of the information presented. However, there have been times where I felt that it was important to highlight issues that are very unique to a given C++ class, for example. I have created sections like "Performance Considerations" when I want to caution users to not use an object in certain situations.