Re: Types, packages & objects : the good old naming conventions question (without religious ware)

[Stephen Leake <stephen_leake@stephe-leake.org>]

"Jeffrey R. Carter" <spam.jrcarter.not@spam.acm.org> writes:

> Stephen Leake wrote:
>>
>> Why should I have to waste time on this?
>
> The time is not wasted. I've said before that _T[ype] is an excuse for
> not doing necessary thinking. Good names document the code and make it
> easier to understand; mindlessly adding _T[ype] to a general concept
> name for the type name and mindlessly using the general concept name
> for all parameters and objects of the type doesn't. If you don't spend
> the time and effort involved to think about and use good names, then
> everyone who reads the resulting code has to do the equivalent
> thinking to understand the code.

Yes, you need to pick good names. Having picked good names, why waste
_more_ time picking _different_ names for type vs object?

> When you see
>
> Append (List => List, Element => Element);
>
> you don't really know what's being appended to what. 

In a purely generic context, like in the body of
Ada.Containers.Indefinite_Doubply_Linked_LIsts, that is precisely what
you should know.

What's wrong with that?

Ah, perhaps you mean "am I appending Element to List, or List to
Element"? I don't think that's a reasonable objection; List is clearly
the container, here, given the English meanings of the words.

> Compare that to
>
> Append (Onto => Widget_List, Item => Next_Widget);

In the body of a container of widgets, yes, this is appropriate.

I don't see any difference between "Item" and "Element";
Ada.Containers uses "Element", SAL uses "Item".

"Onto" almost makes sense, because "Append this onto that" is proper
English. Note that the order in the code is wrong, though! 

But in a package containing several operations on an abstract type,
it's better to use the same name for the abstract type parameter in
all operations. Otherwise the user has to keep checking what that name
is:

Op_1 (onto => list, element => object_1);
Op_2 (from => list, element => object_2);
Op_3 (container => list, element => object_3);

It's much easier if it's always "list => list".

-- 
-- Stephe