Canonical Function Structure

Here is a proposed canonical structure for functions/procedures. Clearly in some cases some sections would not be present. What’s important is to understand the basic phasing of the work to be done and the separation of tasks.

int foo(

     char *StringIn, // “in” parameter

     size_t BufferLength, // “in” parameter

     char Buffer[], // “out” parameter, max length governed by BufferLength

     size_t *CharsWritten // “out” parameter, must be <= BufferLength

     ) {

     // Phase 1: Initialize out parameters

     *CharsWritten = 0;

     // Phase 2: Capture and validate parameters

     const size_t StringInLength = strlen(StringIn);

     if ((BufferLength != 0) && (Buffer == NULL))

return ERR_INVALID_PARAMETER;

     // Phase 3: do work

if (BufferLength <= StringInLength)

     return ERR_BUFFER_TOO_SMALL;

     memcpy(Buffer, StringIn, StringInLength);

     Buffer[StringInLength] = ‘\0’;

     // Phase 4: copy data out

     *CharsWritten = StringInLength + 1; // safe because BufferLength is > StringInLength so “+1” won’t overflow

     // Phase 5: goodbye

     return ERR_SUCCEEDED;

}

There may be other phases and the example’s perhaps kind of dumb but I think it works well to call out what kinds of operations should happen in which phases and even more so what doesn’t have to happen later on given work that occurred earlier.