Re: c++ class design: where to put debug purpose utility class?
On Jun 30, 1:21 pm, Ian Collins <ian-n...@hotmail.com> wrote:
James Kanze wrote:
On Jun 30, 9:35 am, Ian Collins <ian-n...@hotmail.com> wrote:
James Kanze wrote:
[...]
Where we
disagree is that you seem to consider the unit tests a form of
being "written down", whereas I consider them code, just like
the rest---I don't know how to write a unit test until I have
some idea what is to be tested, i.e. what the unit shoud do.
And IMHO, I don't know that until it is written down.
Not really, the written down will be some form of requirement, be that a
clause in a traditional requirements specification, or an XP style user
story. Given a requirement, my view of TDD is that it's another form of
functional decomposition. You know what your end gaol is, you know the
steps to take you there and you follow them. The smaller those steps,
the better.
(I presume you mean "your end goal", but it's an interesting
Freudian slip:-). Except that you're probably American, and
would have written jail, and not gaol.)
The smaller the steps, the better, but to get the small steps,
you have to know the big ones. In a small application, you can
possibly go directly from user requirements to a detailed
specification of each unit, but as soon as the application takes
on a certain size, you're going to end up "designing" a number
of intermediate levels. (In many large applications, the first
couple of levels of functional decomposition give processes, not
what you'd normally consider a target for a unit test.)
For small applications, it's not unusual that the "written down"
part ends up as comments in the header (in Doxygen format, for
example). For larger applications, there'll almost always be
some sort of high level functional decomposition before I can
even think about "units", and that has to be written down.
With TDD, the names of the tests replace the comments.
I'd be interesting in seeing that. For example, in a class that
I'm using right now, certain functions are documented with
'precondition: itemname != NULL". For a user, that's a very
important precondition. How do you specify that in a test, and
make it readable? How do you organize things so that I can
easily find the functions which interest me, and then see the
documentation which concerns them?
Everything I've ever seen and done suggests that you really need
separate detailed documentation, and that it is best done before
writing a single line of code, test or implementation. Literate
programming, in sum. (In the best run projects I've been on,
the header files were actually generated automatically from the
class documentation, done in Rational Rose.)
The tests are the detailed design and the examples of how to
use the code. The acceptance tests are the higher level
requirements. If these are written correctly, either by the
customer or in a form they can understand, the paper
requirements can be discarded. I have only had one client
bold enough to do this!
I'm very sceptical. I don't want to have to read C++ when I
need more general information, like the pre-conditions. Even
supposing that there are tests that reveal them, how do you
avoid the information getting lost in all of the other detail.
Often with TDD, you test and to code to a more abstract
requirement and the design (classes) follow the tests.
Traditionally, that has been called prototyping, not
testing:-). It's almost essential for anything which
interacts with a human. It's of almost no use if you're
implementing a protocol defined by a standard.
Traditionally, you're supposed to throw the prototype out,
once you've learned from it. A rule that is often ignored
(which may account for the poor quality of some of the
software out there). But I suppose that you could call
throwing it out simply an intensive refactorizing, and the
prototyping "testing". Especially since the "throwing out"
usually doesn't consist of actually deleting the source code
from the disk, and that the rewrite often involves some
copy/pasting:-).
Refactoring is part of the process of improving the design. I
think you would enjoy "Refactoring to Patterns" by Joshua
Kerievsky.
The problem is perhaps more psychological. If someone is told
that they are to refactor some code, they will generally try to
use the original code, even (perhaps) to the point of "forcing"
the new design in order to do so. I know that many recent
authors about refactoring insist on not being afraid to rewrite.
But the name itself suggests that you're doing something to the
old code (other than just throwing it out). Where as I prefer
to take the approach that you're starting from scratch, top
down; if some of the existing code does turn out to fit into the
new design (and it often does), so much the better, but this
consideration isn't taken into account until after you've done
the new design.
Sometimes there's an agreed interface, or a base class that
is being extended, but often the tests are testing an
action for a reaction.
In which case, you probably have some idea as to what the
action or reaction should be. And perhaps even some
constraints on it. I'd write those out, in plain French (or
whatever language I happen to be using on the project).
Maybe as comments in the code; maybe even as comments in the
unit tests. But in a human language, at a higher level of
abstraction than C++.
While I'd write them out as plain C++ or what ever language I
happen to be using on the project! In a way, they are in
plain English, so long as the tests are short and have
meaningful names. That's why I always forward declare the
tests at the top of a file, even if the language (such as PHP)
does not require this. If the test's name can't express its
intent, the scope of the test is too broad.
I'm still quite sceptical: I suppose that you also break the
tests into sections, perhaps with different namespaces, in order
to specify exactly what functions (or functionalities) are
concerned? And what about "external" references---often, an
idea can be made much clearer by refering to some external
concepts. (The documentation of my FFmt class: "An ostream
manipulator which defines a Fortran format F. Thie manipulator
is basically the equivalent to the "%n.mF" speicification in
printf, or Fn.m in Fortran." How could you possibly express
that in the name of a single test function? Of course, it's not
complete; the documentation does go on to express in detail what
is going on---with references to a pattern described in another
class---but for many programmers, just that one sentence is all
that is needed.) And how do you possibly describe the
constraints on a policy class, used to instantiate a template?
And that's just the low level stuff. The higher up you go, the
less appropriate C++ becomes as the description language.
I don't think anyone is suggesting that. What is being
suggested is a different way of thinking.
Well, I've said from the start that you can't write any code
without first thinking. Including a unit test. But I'd
like to insist on the fact that if you haven't written it
out in your native language, you haven't really thought it
out.
To varying degrees of 'it'!
I like to class the design and naming of the tests as an
important part of this thinking process. The name
(meaningful) and size (small) of the tests is extremely
important.
Certainly. At the lowest level, I can imagine your solution
working for some types of things. I don't see too well how it
could apply at higher levels, however, and I don't see how it
could be used for other types of low level things. How would
you document that the instantiation class of std::vector must be
CopyConstructable and Assignable, for example? How would you
document the requirements for the Allocator? For that matter,
do you really want to document them for std::vector, given that
they're the same for all of the containers; isn't the solution
adopted by the standard a lot better: give the concepts a name,
and document what that name means elsewhere (which, when it
comes right down to it, is what I did with FFmt---except that I
suppose the name, Fn.m in Fortran, to be an already known
concept).
All to often I see novices write a monolithic test
function with scores of asserts which tell the reader very
little. Break that up into a sequence of well named single
condition tests and the reader can see exactly what the code
is supposed to do. Many small, well named tests is a clear
indicator that some who claims to be doing TDD is. He or she
can then tell what they have broken when they make a change
without having to step through the test.
Guilty as charged. My current test framework certainly doesn't
lend itself to this sort of stuff. But then, I've never been
motivated to modify it so that it would, since I do work in the
opposite direction: from specification and documentation to
code. Still, I'd be interested in seeing what you use as a test
framework---I'm currently rewriting parts of mine to accept test
specifications in XML, so it's a good occasion to integrate new
ideas.
FWIW: you can see a bit of my work at my site
(kanze.james.neuf.fr). It doesn't explain how I got to that
state, but for most of the stuff: I wrote the documentation in
the header file first, then the function signatures. The
implementation of the functions and the tests were generaly done
in parallel, and in the more complicated cases, I'd start with
just a few of the function signatures, and expand once they
worked. There are more tests than I've seen in a lot of
publicly available software, but it could still be better.
--
James Kanze (GABI Software) email:james.kanze@gmail.com
Conseils en informatique orient=E9e objet/
Beratung in objektorientierter Datenverarbeitung
9 place S=E9mard, 78210 St.-Cyr-l'=C9cole, France, +33 (0)1 30 23 00 34