Re: [PATCH] api-allocation-growing.txt: encourage better variable naming

[Junio C Hamano <gitster@pobox.com>]

Adam Spiers <git@adamspiers.org> writes:

> The documentation for the ALLOC_GROW API implicitly encouraged
> developers to use "ary" as the variable name for the array which is
> dynamically grown.  However "ary" is an unusual abbreviation hardly
> used anywhere else in the source tree, and it is also better to name
> variables based on their contents not on their type.

Sounds good.  To follow "not type but contents", a further rewrite
with s/array/item/ is even better, no?

I can obviously squash it in without resending, if you agree, or you
can point out why item[] is not a good idea and array[] is better.

>
> Signed-off-by: Adam Spiers <git@adamspiers.org>
> ---
>  Documentation/technical/api-allocation-growing.txt | 14 ++++++++------
>  1 file changed, 8 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/technical/api-allocation-growing.txt b/Documentation/technical/api-allocation-growing.txt
> index 43dbe09..3894815 100644
> --- a/Documentation/technical/api-allocation-growing.txt
> +++ b/Documentation/technical/api-allocation-growing.txt
> @@ -5,7 +5,9 @@ Dynamically growing an array using realloc() is error prone and boring.
>  
>  Define your array with:
>  
> -* a pointer (`ary`) that points at the array, initialized to `NULL`;
> +* a pointer (`array`) that points at the array, initialized to `NULL`
> +  (although please name the variable based on its contents, not on its
> +  type);
>  
>  * an integer variable (`alloc`) that keeps track of how big the current
>    allocation is, initialized to `0`;
> @@ -13,22 +15,22 @@ Define your array with:
>  * another integer variable (`nr`) to keep track of how many elements the
>    array currently has, initialized to `0`.
>  
> -Then before adding `n`th element to the array, call `ALLOC_GROW(ary, n,
> +Then before adding `n`th element to the array, call `ALLOC_GROW(array, n,
>  alloc)`.  This ensures that the array can hold at least `n` elements by
>  calling `realloc(3)` and adjusting `alloc` variable.
>  
>  ------------
> -sometype *ary;
> +sometype *array;
>  size_t nr;
>  size_t alloc
>  
>  for (i = 0; i < nr; i++)
> -	if (we like ary[i] already)
> +	if (we like array[i] already)
>  		return;
>  
>  /* we did not like any existing one, so add one */
> -ALLOC_GROW(ary, nr + 1, alloc);
> -ary[nr++] = value you like;
> +ALLOC_GROW(array, nr + 1, alloc);
> +array[nr++] = value you like;
>  ------------
>  
>  You are responsible for updating the `nr` variable.