«

Hi,

I have a simple question about naming convention, recommeded names or
so in following case.
I have a class which is implemented with one of STL container
(aggregated) and my aim is to expose iterators to enable user of my
class to iterate through this container content.
Here is a piece of code:

class A;
class C
{
std::vector<A*> v;
public:
// ...
typedef std::vector<Layer*>::iterator Iterator; // 1)
Iterator Begin() { return v.begin(); } // 2)
Iterator End() { return v.begin(); } // 3)
}

Obviously, in line 1) I'm declaring another (typedef) name for
std::vector<Layer*>::iterator.
In lines 2) and 3) I have accessor to std::vector<Layer*> iterators.

My questions are:

- Is it safe to rename iterator as in this example
std::vector<T>::iterator to Iterator?
- Is it safe to rename std::vector<T>::begin to Begin and
std::vector<T>::end to End?
- Are those names safe in case of using objects of C class in STL
algorithms?
- Any better recommendation?

What's the purpose of those names?
Simply, I'd like to get them more coherent with naming convention I use
in my project.

Cheers
--
Mateusz Loskot
http://mateusz.loskot.net

Mateusz Loskot wrote:
> I have a simple question about naming convention, recommeded names or
> so in following case.
> I have a class which is implemented with one of STL container
> (aggregated) and my aim is to expose iterators to enable user of my
> class to iterate through this container content.
> Here is a piece of code:
>
> class A;
> class C
> {
> std::vector<A*> v;
> public:
> // ...
> typedef std::vector<Layer*>::iterator Iterator; // 1)
> Iterator Begin() { return v.begin(); } // 2)
> Iterator End() { return v.begin(); } // 3)
> }
;
^^^
Apparently, the semicolon is missing.

>
> Obviously, in line 1) I'm declaring another (typedef) name for
> std::vector<Layer*>::iterator.
> In lines 2) and 3) I have accessor to std::vector<Layer*> iterators.
>
> My questions are:
>
> - Is it safe to rename iterator as in this example
> std::vector<T>::iterator to Iterator?

You're not _renaming_ it. You're introducing a _local_ *synonym* for
it. The locality is the scope of the 'C' class. And why do you ask?
What could be _UN_safe about it? What are your concerns? You could
have just used the non-capitalized version of the word, it would be
probably simpler and more familiar for most who use iterators in
their everyday C++ activities. Capitalization is awkward. Java-like.

> - Is it safe to rename std::vector<T>::begin to Begin and
> std::vector<T>::end to End?

You're not _renaming_ anything here. You're calling 'C's members
whatever you would like them to be called. What's all the fuss
about?

> - Are those names safe in case of using objects of C class in STL
> algorithms?

Huh... "Safe"? I still can't understand your concern with "safety"
here. What is it you are afraid of? Example: when I say it is not
safe to drive on a slippery road without seatbelts, I am afraid of
the injuries that can resuld from car veering off the road and hitting
an obstacle.

When you use objects of your 'C' class (BTW, names consisting of one
letter only are really "unsafe", from maintenance point of vive) with
Standard Library algorithms, for example, 'copy' or 'transform', you
are _forced_ to spell out your names. The Standard Library algorithms
do _not_ expect your objects to have "begin" and "end" functions.

> - Any better recommendation?

Unless you actually get an error, stop asking those nonsensical
questions. Get a drink, go out, breathe some fresh air, ventilate
your brain (but not by drilling more holes in your head).

> What's the purpose of those names?

Which ones? If you're asking about your "Begin" and "End" names, then
_we_ cannot answer your question. Those names _you_ invented. _You_
are the one who knows their purpose.

> Simply, I'd like to get them more coherent with naming convention I
> use in my project.

Conventions are just that, conventions. You agree on something. It
doesn't have to be "like everybody else", but it doesn't necessarily
be "unlike everybody else's". Unless you experience some _trouble_,
stop wasting your time on trying to figure out the best convention,
just follow _one_ (and one in the Standard Library is not the worst).

V

In C class you encapsulated std::vector. It has original not "STL like
interface". It's OK - its your decision. However from my point of view
there is a possibility of following drawbacks in future:
1) vector have a lot of methods - if in future you decide to use more
of them you will add them to C class. Finally C class will look like
std::vector. Question is - whay can't you use vector from the very
beginning?
2) You use End() instead of end(). Experienced STL developers will hate
you for this. Everybody knows how to iterate collection. To do this one
use end(), begin(), iterator. And not End(), ...
3) If you decide to remove C class (see p.1 above), you will be forced
to replace End() to end() etc in numerous places.

Victor Bazarov wrote
> Mateusz Loskot wrote:
>
> ;
> ^^^
> Apparently, the semicolon is missing.

Yes.

> >
> > My questions are:
> >
> > - Is it safe to rename iterator as in this example
> > std::vector<T>::iterator to Iterator?
>
> You're not _renaming_ it.

Yes, "rename" is unfortunate here.

> You're introducing a _local_ *synonym* for it.

Definitely, "synonim" the right name.

> The locality is the scope of the 'C' class. And why do you ask?
> What could be _UN_safe about it?

I ask because I don't know if what I've introduced it fine or not.

> What are your concerns? You could
> have just used the non-capitalized version of the word, it would be
> probably simpler and more familiar for most who use iterators in
> their everyday C++ activities.
> Capitalization is awkward. Java-like.

Definitely, agreed.
First, I have types and methods named with first letter upper case (not
getMe but GetMe).
I know it's awkward, so please don't ask me why I use it Simply, I
have to.

My question is of kind of this "Is that safe to use names with
double-/single- underscore as a first character?".
So, I hoped it will be clear why I ask.

> > - Is it safe to rename std::vector<T>::begin to Begin and
> > std::vector<T>::end to End?
>
> You're not _renaming_ anything here.

Yes, it's confirmed. "Synonim" is the right word.

> You're calling 'C's members
> whatever you would like them to be called. What's all the fuss
> about?

OK, I'm calling a member, that's clear and I get a typedef of
std::vector<T>::iterator, a synonim, so can I pass it to STL
algorithms?

Simply, is this code below OK regarding iterators usage?

std::vector<MyClass> v;
typedef std::vector<MyClass>::iterator ThisIsMySynonim;
ThisIsMySynonim MyBegin() { return v.begin(); }
ThisIsMySynonim MyEnd() { return v.end}
std::for_each(v.MyBegin(), v.MyEnd(), FunctorDefinedSomewhere());

> When you use objects of your 'C' class (BTW, names consisting of one
> letter only are really "unsafe", from maintenance point of vive)

It's a short for Usenet so the code does not occupy too much space in
post.

> Standard Library algorithms, for example, 'copy' or 'transform', you
> are _forced_ to spell out your names. The Standard Library algorithms
> do _not_ expect your objects to have "begin" and "end" functions.

And that's what I'm asking for too. Thanks.


> > - Any better recommendation?
>
> Unless you actually get an error, stop asking those nonsensical
> questions. Get a drink, go out, breathe some fresh air, ventilate
> your brain (but not by drilling more holes in your head).
> [...]

Hehe, you are definitely right. It was about 5 am so it was a good idea
to go to bed, no discussion here.

> > Simply, I'd like to get them more coherent with naming convention I
> > use in my project.
>
> Conventions are just that, conventions. You agree on something. It
> doesn't have to be "like everybody else", but it doesn't necessarily
> be "unlike everybody else's". Unless you experience some _trouble_,
> stop wasting your time on trying to figure out the best convention,
> just follow _one_ (and one in the Standard Library is not the worst).
>

Hm, interesting, I've read somewhere (I cannot recall where I read it,
may be in Scott Meyers' books, but I'm not sure now) that STL coding
style is just for STL and should not be followed in external
(non-STL/Standard C++) implementations. I've understood is just as
chapter 17.4.3.1.2 from C++ Standard, as a good recommendation.
Certainly, I may be wrong.

Thanks for your patience!
Cheers
--
Mateusz Loskot
http://mateusz.loskot.net

Dervish wrote:
> In C class you encapsulated std::vector. It has original not "STL like
> interface". It's OK - its your decision. However from my point of view
> there is a possibility of following drawbacks in future:
> 1) vector have a lot of methods - if in future you decide to use more
> of them you will add them to C class. Finally C class will look like
> std::vector. Question is - whay can't you use vector from the very
> beginning?
> 2) You use End() instead of end(). Experienced STL developers will hate
> you for this. Everybody knows how to iterate collection. To do this one
> use end(), begin(), iterator. And not End(), ...
> 3) If you decide to remove C class (see p.1 above), you will be forced
> to replace End() to end() etc in numerous places.

In addition C++0x may well have algorithms that automatically call
begin() and end() for you that allow you (most algorithms are performed
on whole collections). From that point of view you will probably want
to stick with the begin() and end() names. You might want to also
implement empty() and size() and const-iterators with const overloads
of begin() and end().

I am assuming that what you are showing is a sample and that in
reality, your class has a more descriptive name than C and has more
functionality than simply wrapping a vector.

Mateusz Loskot wrote:
> Hi,
>
> I have a simple question about naming convention, recommeded names or
> so in following case.
> I have a class which is implemented with one of STL container
> (aggregated) and my aim is to expose iterators to enable user of my
> class to iterate through this container content.
> Here is a piece of code:
>
> class A;
> class C
> {
> std::vector<A*> v;
> public:
> // ...
> typedef std::vector<Layer*>::iterator Iterator; // 1)
> Iterator Begin() { return v.begin(); } // 2)
> Iterator End() { return v.begin(); } // 3)
> }
>
> Obviously, in line 1) I'm declaring another (typedef) name for
> std::vector<Layer*>::iterator.
> In lines 2) and 3) I have accessor to std::vector<Layer*> iterators.
>
> My questions are:
>
> - Is it safe to rename iterator as in this example
> std::vector<T>::iterator to Iterator?
> - Is it safe to rename std::vector<T>::begin to Begin and
> std::vector<T>::end to End?

Sure. Don't worry too much. The iterator for int Array[N] is called
int*, the
begin 'function' is &Array[0] and the end is &Array[N]. The STL can
work
with those.

Of course, even though the compiler doesn't care, your readers will.
Extra
names aren't bad, but if you don't have begin() and end(), they won't
think
it's a container designed to fit in the STL framework.

HTH,
Michiel Salters

Earl Purple wrote:
> Dervish wrote:
> > In C class you encapsulated std::vector. It has original not "STL like
> > interface". It's OK - its your decision. However from my point of view
> > there is a possibility of following drawbacks in future:
> > 1) vector have a lot of methods - if in future you decide to use more
> > of them you will add them to C class. Finally C class will look like
> > std::vector. Question is - whay can't you use vector from the very
> > beginning?

My collection is highly specialized, but based on std::vector or
std::list.
It also provides functions like MoveToTop, MoveDown, MoveUp,
MoveToBottom etc.

> > 2) You use End() instead of end(). Experienced STL developers will hate
> > you for this.

Yes, I'm affraid of that

> Everybody knows how to iterate collection. To do this one
> > use end(), begin(), iterator. And not End(), ...

That's right. I'm pretty convinced. Thanks to Victor too.

> > 3) If you decide to remove C class (see p.1 above), you will be forced
> > to replace End() to end() etc in numerous places.

Hm, may be I should hide algorithms behind methods as Scott Meyers
suggest in his "Effective STL", suggestion 44.

> In addition C++0x may well have algorithms that automatically call
> begin() and end() for you that allow you (most algorithms are performed
> on whole collections). From that point of view you will probably want
> to stick with the begin() and end() names. You might want to also
> implement empty() and size() and const-iterators with const overloads
> of begin() and end().

As I said, I become convinced
Your arguments are clear.

> I am assuming that what you are showing is a sample and that in
> reality, your class has a more descriptive name than C and has more
> functionality than simply wrapping a vector.

That's right.

Cheers
--
Mateusz Loskot
http://mateusz.loskot.net

Thanks for your input.

I'm glad that Victor pointed possible problems.
I'd really like to have a very simply but well defined coding style.
I've read John Lakos' book "Large-Scale C++ Software Design" and after
this discussion here I'm a bit confused. I thought John's idea of
coding style is very clear and simple.
But in chapter 1.4.1.1 John states that names of types (not data or
functions) with first letter upper-case and I tried to follow it
writting:

typedef std::vector<T>::iterator Iterator;
or (whatever)
typedef std::vector<T>::iterator MyIterator;

But Victor reproved me for that is's inconsistent with STL naming
convention and may confuse users of my class. And he is right

Cheers
--
Mateusz Loskot
http://mateusz.loskot.net

Mateusz Loskot wrote:
> I'd really like to have a very simply but well defined coding style.
> I've read John Lakos' book "Large-Scale C++ Software Design" and after
> this discussion here I'm a bit confused. [...]

Don't take any book as absolute truth, regardless of the number of copies
printed/sold/given away.

Style cannot be good by itself. As soon as you start working in a group,
you will put your style to the test. Adjust as needed.

Conclusion: write what feels good to read. If you like capitalisation,
and nobody [else] who reads your code complains, keep the capitalisation.

V

Victor Bazarov wrote:
> Mateusz Loskot wrote:
> > I'd really like to have a very simply but well defined coding style.
> > I've read John Lakos' book "Large-Scale C++ Software Design" and after
> > this discussion here I'm a bit confused. [...]
>
> Don't take any book as absolute truth, regardless of the number of copies
> printed/sold/given away.

Yes, that's the truth what you are saying.
But I think it's useful to have some references, examples and
possibilities and then to develop something on my own based on that, in
example coding style.

>
> Style cannot be good by itself. As soon as you start working in a group,
> you will put your style to the test. Adjust as needed.
>
> Conclusion: write what feels good to read. If you like capitalisation,
> and nobody [else] who reads your code complains, keep the capitalisation.
>

Yes, you are right again.
My major aim is to develop coding style as much consistent as possible.
So, I'd like to avoid mutually exclusive rules and occurences like
those:

1) Rule: Every type starts with capital letter
2) Next, I have my library strongly based on STL and I'd like to
provide STL coherent interface so I have in one of my class:

class A
{
public:
typedef std::string::size_type size_type;
size_type size() const;
};

And here size_type breaks the rule defined in 1).
Yes, according to this rule in 1) I could write:

typedef std::string::size_type SizeType;
SizeType size() const;

But, users of my library learn (from documentation etc.) that
collection-like or collection composition classes in my library provide
number of elements through size() function, just like STL std::vector
or std::string does it and the type of return value is ....size_type
but not ...SizeType.
Simply, it breaks inconsistency, doesn't it?
I hope I provide clear example now.

Cheers
--
Mateusz Loskot
http://mateusz.loskot.net