Structuring class implementations

[Martin Drautzburg]

Hello all

Being farily new to C++ I have some questions concerning the structuring
of class implementations:

(1) Categories

Having some smalltalk background, I would like to group the methods of a
Class into categories like "Initializing", "Accessing" and the like.
This is basically an IDE question. I am using eclipse and the "Outline"
shows all my methods, but I cannot seem to get them structured, I can
only sort them.

(2) Class::Method

Is there a way to avoid repeating the Class name in front of a method
implmentation? I would much rather put something at the beginning of
all method implementations for one class. I tried "using"
and "namespace" but I could not figure it out.

Ideally I would want my implementation look something like this

ImplementationOf(Class1) {
MethodsFor(Initializing) {
method1(){...} // not Class1::method1
method2(){...}
}
MethodsFor(Accessing) {
method3(){...}
method4(){...}
}
}

 

[Martin Drautzburg]

// C.h
class C {
public:
void f() { /* ... */ } // inline
void g();
};

Well, I know that. Whats puzzeling me is that there is a way to
structure member functions on declaration level (by putting class C {}
around it) but not on implementation/definition level. The only
possible "brace" I am aware of is file membership, i.e. I could put
implentations into different files. The question is: is this really the
only way?

 

[jason.cipriani]

 Well, I know that. Whats puzzeling me is that there is a way to
structure member functions on declaration level (by putting class C {}
around it) but not on implementation/definition level.

Yes. "Namespaces" have a syntax similar to what you're talking about
(you can put "namespace { ... }" around an entire set of definitions),
but namespaces are not classes, I'm only mentioning them because of
the syntax.

The only
possible "brace" I am aware of is file membership, i.e. I could put
implentations into different files.

I'm not sure what you are referring to, but yes, you could put
implementations in different files. As long as the definition is
available *somewhere*, it will satisfy the linker.

The question is: is this really the
only way?

Yes. There are exactly two places you can put member function
definitions. You can put them inline, right in the declaration:


class MyClass {
public:
void f () {
// implementation
}
void g () [
// implementation
}
};


And you can put them outside of the declaration:


class MyClass {
public:
void f ();
void g ();
};

void MyClass::f () {
// implementation
}

void MyClass::g () {
// implementation
}


You can also mix the two for a given class. If the definitions are
outside the declaration, it is entirely up to you what source files
you want to put the definitions in, although personally I find it
easiest to stay organized if every class has a dedicated header with
the declarations, and a source file with the definitions.


HTH,
Jason

 

[Martin Drautzburg]

outside the declaration, it is entirely up to you what source files
you want to put the definitions in, although personally I find it
easiest to stay organized if every class has a dedicated header with
the declarations, and a source file with the definitions.

That the way you have to do it in Java and it does help somewhat. What I
don't like about it, is that you may hesitate to create an extra class,
because you have to create two new files in C++ (one file in Java,
except you are doing EJB stuff, where you have to create four files).

This is something I really like about e.g. Python: creating a class is
not more work than creating a function, so it does not require any
discipline to put something into an extra class if that makes things
clearer.

But the one-class-one-file idiom creates another problem: when you
create lots of little classes, you cannot see what *classes* belong
together. You need another structuring element. I suppose you can use
directories for that. Again this is what they do in Java and I don't
particularily like it. It just scatters things too much.

I recently started using Doxygen for documenting my code and it does a
good job on structuring things. There I *can* group classes into
modules and member functions into member categories which makes the
whole thing a lot more comprehensible. It is really fun reading that
documentation and it even lets you find flaws. I only wish I could come
close to that browsing experience with eclipse's CDT C++ tools.

 

[James Kanze]

(e-mail address removed) wrote:

If the definitions are

That the way you have to do it in Java and it does help
somewhat. What I don't like about it, is that you may hesitate
to create an extra class, because you have to create two new
files in C++ (one file in Java, except you are doing EJB
stuff, where you have to create four files).

That's not totally true. C++ doesn't impose any particular
organization: you could put all of your classes in a single
header file, for example.

Good design generally suggests that header files be both minimal
and complete---typical requirements for a class, so there is a
tendency of one class/one header. But there are certainly
exceptions; if you have two classes that can only be used
together, then it makes sense to put them in a single header,
and if one class is only used to access certain features of
another, it makes sense to make it a nested class. (A good
example of the first would be invasive reference counting, where
all of the objects pointed to by RefCntPtr<> must derive from
RefCntObj. A good, and very widespread, example of the second
would be iterators or proxies.)

How the source files are divided up depends a lot on what you
are doing. In a well written, general purpose library,
practically every non-virtual function will be in a file of its
own. In other cases, it makes sense to both define and
implement helper classes in the same source file as the class
which uses them.

In the end, the organization should be based on sound
engineering principles. And there's no real reason to worry
about the number of source files, or even the number of header
files, involved; it normally doesn't take any more time to
create a function in a new file than to create it in an existing
file.

This is something I really like about e.g. Python: creating a
class is not more work than creating a function, so it does
not require any discipline to put something into an extra
class if that makes things clearer.

C++ is statically typed, and designed for large projects. This
means that in many cases, the person who defines the public
interface will not be the person who implements it; it will also
be reviewed at a different level.

But the one-class-one-file idiom creates another problem: when
you create lots of little classes, you cannot see what
*classes* belong together. You need another structuring
element. I suppose you can use directories for that. Again
this is what they do in Java and I don't particularily like
it. It just scatters things too much.

Finding a good multilevel organization is an art, and no matter
what you do, you'll end up thinking that some other organization
would have been better. I'm not sure to what degree this is a
reflection of the truth, and to what degree it is just "the
grass is always greener on the other side of the fence."

I recently started using Doxygen for documenting my code and
it does a good job on structuring things. There I *can* group
classes into modules and member functions into member
categories which makes the whole thing a lot more
comprehensible. It is really fun reading that documentation
and it even lets you find flaws. I only wish I could come
close to that browsing experience with eclipse's CDT C++
tools.

Yes. Doxygen is very good in that respect. The only real
problem is that it requires you to work backwards. You normally
want to have the documentation before you start writing the
code, at least where interfaces are concerned.

 

[jason.cipriani]

(e-mail address removed) wrote:

If the definitions are


That the way you have to do it in Java and it does help somewhat. What I
don't like about it, is that you may hesitate to create an extra class,
because you have to create two new files in C++ (one file in Java,
except you are doing EJB stuff, where you have to create four files).

You don't *have* to do it that way, of course. C++ is flexible there.
If you'd like to put many classes in one source file, you have that
option. In a larger project, things may start to get a little hectic,
though.

This is something I really like about e.g. Python: creating a class is
not more work than creating a function, so it does not require any
discipline to put something into an extra class if that makes things
clearer.

But the one-class-one-file idiom creates another problem: when you
create lots of little classes, you cannot see what *classes* belong
together. You need another structuring element. I suppose you can use
directories for that. Again this is what they do in Java and I don't
particularily like it. It just scatters things too much.

FWIW, certain IDE's also help with that type of organization. For
example, Visual Studio allows you to categorize your source files into
"folders" in a project explorer independently of how they are
organized in the file system. I believe Dev-C++ allows you to do this
as well.

Same goes for Java, certain IDE's can ease the pain. Eclipse, for
example, shows the packages as a tree in the project view, and even
though it's tied to the file system, navigation through packages is
arguably convenient. Javadoc-generated documentation (or doxygen for C+
+) also pulls everything back into one convenient place.

If you're working on even a moderately sized project, but only using,
say, notepad/pico/textpad and a command line compiler, things are
going to get scary quickly no matter what language you're coding in.

I recently started using Doxygen for documenting my code and it does a
good job on structuring things. There I *can* group classes into
modules and member functions into member categories which makes the
whole thing a lot more comprehensible. It is really fun reading that
documentation and it even lets you find flaws. I only wish I could come
close to that browsing experience with eclipse's CDT C++ tools.

I've never used Eclipse for C++. I've always been loyal to Visual
Studio on Windows, it has a lot of really nice organization and
browsing features. On Linux, I'm not sure what's available, somehow I
always seem to get by with XEmacs. On OS X, XCode is the norm but I
don't do enough Mac development to comment on it.

Jason

 

[Martin Drautzburg]

Thanks so much for your advice.

I finally discovered Eclipse's Type hierarchy browser and it at least
lets me see all members of one class and it brings me directly to the
implementation regardless in which file it lives. That's about 50% of
what I was looking for. Method categories would be nice though, but
hey.

 

[jason.cipriani]

Thanks so much for your advice.

I finally discovered Eclipse's Type hierarchy browser and it at least
lets me see all members of one class and it brings me directly to the
implementation regardless in which file it lives. That's about 50% of
what I was looking for. Method categories would be nice though, but
hey.

Well, hey, you know, an Eclipse plug-in to, say, parse specially
formatted code comments and provide a category view of names might be
a fun little Java side project.

Jason

 

[Matthias Buelow]

Well, hey, you know, an Eclipse plug-in to, say, parse specially
formatted code comments and provide a category view of names might be
a fun little Java side project.

Or not.

 

[jason.cipriani]

Or not.

That might also be true!