3. Development Definitions

These are terms that, when used in the context of software development, are very helpful to strictly limit their use to to the definitions below.

A software project (code and documentation) that does so has the quality that they are easiest to learn and understand because the code and documentation are both precise and unambiguous. This quality increases understandability in both the project’s source code and its documentation.

address

A location in RAM or PROGRAM SPACE - it’s the value that is loaded on an ADDRESS BUS (by a CPU) in order to read from or write to some kind of storage medium (internal or external RAM) or external device on the other side of that address bus. Example usage of “address”: “DDR starts at address 0x88000000 when being accessed through a cache.”

offset

A distance (in bytes) from a (specified or understood) base point. In files, if the base location is not stated explicitly, then the understood “base location” is offset 0 - the beginning of the file. Example: “What is the offset of the first pixel in the bitmap file?” You can also be explicit about the base point instead of having it be understood. Example: “‘Stride’ is the offset from pixel (0,0) to pixel (0,1).”

pointer

A variable that contains an address. Never use the term “pointer” to mean offset, and never use it to mean index. I see these 3 terms used interchangeably by (apparently) new programmers and sometimes electronics engineers who don’t know any better, and it serves to make it that much more difficult and time consuming to understand what they mean, given the ambiguity it creates. Example: “Using pointers can reduce the number of instructions required to access arrays.” Using this definition, you can add an integer value to a POINTER and get another address, but you can never add a POINTER to a POINTER.

size

When used alone (i.e. when no units are specified), “size” is always the number of bytes a “thing” (object) has. If you want to talk about an array, for example, if you use the term “size” without qualifying it, it is always in BYTES. The other way to express array size is in “number of elements”, but in that case we try very hard to be explicit about it, e.g. “the array has 512 uint32_t elements”.

Note carefully that this is NOT the same as sizeof(type), which, to the dismay of many programmers, is not really the size of an object or data type, but is explicitly the distance (in bytes) between two adjacent elements in an array of that data type, and CPU (and thus compiler) alignment constraints apply in full. Thus sizeof(type) for custom data types can be different on different platforms unless the programmer has been very careful to eliminate padding between fields and between elements, for all the platforms that data type will be used on.

capacity

When used alone (i.e. the units are not specified), “capacity” it is always the number of elements a container can contain. Example: “the uint32_t array’s capacity is 512”. One can always specify the units to mean something else, and still be precise, e.g. “capacity in bytes” or “capacity in number of elements” or “capacity in latitude-longitude coordinate pairs”.

count

The number of “things” (typically in a container of some type, such as in a list, queue, stack or array). COUNT of items in an array-based list is always <= current CAPACITY for that list. The term COUNT always fulfills these formulas for an array-based list:

address_of_last_element           = base_address + ( sizeof(element_type) * (COUNT - 1) )

address_of_next_available_element = base_address + ( sizeof(element_type) * COUNT ).

index

A zero-based element number, where the item at index 0 is the first item, typically of an array or list. The term INDEX always fulfills this formula:

address_of_element_N = base_address + ( sizeof(element_type) * INDEX_OF_ITEM_N ).

length

Unlike the above terms, LENGTH is always tied to the context of the thing it is referring to. In almost every case it means the number of elements in the data container it is referring to. Example: “string length” will always mean the number of characters in a string (whether they are wide characters, unicode, or ASCII). However, outside the context of strings, COUNT is more explicit and less ambiguous, and is therefore the preferred term.

element

A “thing” stored in a simple storage container such as an array or list.

entry

A “thing” (regardless of its complexity) stored in a more complex data structure such as a hash table or dictionary.