Array index vs. "user documentation" terminology?

Question

I have an "array" of bytes that is referenced in some high-level client/developer documentation (which does not contain any programming language or environment specific information). In this document, bytes are currently referred to as "byte 3" or "byte 17", etc. The development environment is C/C++ and the bytes are stored in an array in which the starting index is 0 (naturally).

The problem is that developers may (have) interpreted "byte 3" in the document as meaning either myarray[3] or myarray[2].

What kind of terminology do folks use to make the "byte number" vs. "array index" distinction clear, yet keep it readable to both (non-programmer) clients and developers?

Answer 1

What kind of terminology do folks use to make the "byte number" vs. "array index" distinction clear, yet keep it readable to both (non-programmer) clients and developers?

Array indices start at 0. (Or, 1. Take a stance and state it in your design document.)

Answer 2

Check in the documentation if exists a "byte 0".

Answer 3

One possibility is to just directly state where you're starting counting. Another possibility is to use things like "first byte", "seventeenth byte", and so on. A third (the one I usually prefer) is to speak in terms of offsets from the base address.

Answer 4

You could remove all reference to the position in the array from your documentation.

Give things a meaningfull name.

Then have constants in your program that map the name to a position in the array.