Use the terms “vector” or “array” in high level discussion of C++ code

Question

When I write high-level documentation about what an algorithm does, I use the term "array" to refer to the data structure on which the algorithm operates even though the actual data structure is an std::vector. I feel that using the term "vector" in this context does not (to me) best convey the meaning I'm after which is "a sequence of elements with constant-time random access" or perhaps more generally "a dynamic array". Is there a convention or common documentation standard for this distinction of similar terms?

Answer 1

I don't know of any standard nomenclature, but like the OP, I prefer using "array" or "dynamic array" for something that has constant-time random access, without specifying the mechanism.

Even though STL uses the term "vector", I come from a mathematics/chemistry background, and do a lot of 2D/3D graphics. In those fields, when you say "vector" in a generic way, it has its linear algebra meaning: a point in an N-dimensional vector space. When I use "vector" in the STL sense, I'm always referring to that specific STL template container.

To me, "list" when applied to containers implies "linked list", which doesn't have constant-time random access. Like Neil Butterworth, I rarely use std::list.

Answer 2

First, know your audience!

I understand from where are you coming from, but If you are writing to C++ people, Use vector. A C++ programmer would know what you mean by vector. Within the C++ context, If you are calling a vector an array, it might be confusing to some folks. IF you still want to use the name "Array", then I will suggest to make a note that you make no distinction between static and dynamic array.

If you are talking to non-technical people, then use the word list or something easier than convey the message (I would still try to define vector because they might get technical later on.)

Good luck!

Answer 3

Interesting. I always use the term "list" as it is (almost) the most degenerate form of a collection, and so the most general. I almost never use std::list in my actual C++ code. however. As a real example from my own code:

 typedef std::vector <unsigned int> FieldList;

Answer 4

We all have our little coding idiosyncrasies, but... come on man!

You're using a vector, why would you call it an array? They're two different things.

An "array" is not a universally known concept. That is, you can't walk up to a random person, ask them what an array is, and expect them to know. So how does that particular word convey the concept of "a collection of elements with constant-time random access" better than "vector"?

Have more faith in your colleagues. Anyone looking over your code who knows what an array is should know what a vector is. And if they don't, you have bigger problems.