Coding Conventions

As with all things telling you how to write your code, take this with a grain of salt. These conventions are just what I try to use and have to bend them myself on occasion. I only present them for those that might be interested, or who want inspiration for coming up with their own style.

constructors/destructor naming

Many coding constructs deal with the creation and deletion of various forms of data or other entities, these operations often follow certain patterns, usually there is a constructor and a destructor which must be matched one to one to insure proper program behavior. data structures may be stack allocated, heap allocated, or be part of a greater memory allocation scheme. The goal of having a consistent naming for these functions and consistent naming of matching pairs of functions is both to help with code clarity and clarity of design and thought when dealing with these types of operations.

init/fini init/fini are used in two similar contexts. in both cases they initialize pre-existing allocated memory, the only difference is where the memory comes from. This is the only function type for which the destructor is not always necessary to clean up all resources.
  • initialization and deinitialization of global structures or subsystems, note that this is equivalent to the second case with a default global structure passed as an argument.
  • filling in and clearing and freeing resources associated with non-opaque statically allocated structures. In this case the functions take an pointer argument to preallocated memory, usually on the stack or statically allocated.
create/destroy These functions are used on purely abstract types which are only dealt with as pointers or some other abstract reference. it is assumed that the create allocates any memory necessary for the structure and the destroy releases any resources used by the structure including the structure itself.
ref/unref These functions work upon abstract structures such as those created with create/destroy. they are used when a reference count is used as a memory management scheme. they interact with create/destroy in the following manner: ref increments a counter and unref decrements it, when it reaches zero then destroy is called. create always returns objects with a reference count of one. destroy destroys objects regardless of reference count.
alloc/free when it is necessary to manage a shared resource pool with the property that any particular instance of a resource is as good as any other then these functions may be used. An example would be the C functions malloc/free, it does not matter which particular block of memory is returned by malloc, only that it is of proper size.
open/close These are analogous to the similar named functions dealing with files in that they are meant for the grabbing and releasing of a handle to a specific stateful or unique resource. The idea is that open is passed a location in some sense of a resource which may be modified and exists beyond the close operation such that a subsequent open operation on the same location will return the same object. This is a deliberately vague description as this method of interaction can be applied to many programming constructs and should not be limited to files.

The preferred usage of these roots to create function names is

as demonstrated in the following examples:
square_t *square_create(color_t color);
void square_destroy(square_t *square);
void lock_manager_init();
void mutex_init(mutex_t *m);
void mutex_fini(mutex_t *m);
stream_t *stream_create_fd(int fd);
stream_t *stream_create_string(char *string);

other naming conventions

My homepage -> computer stuff -> coding style