Re: static inline functions - possible?
On Aug 3, 4:52 pm, Stephen Horne <sh006d3...@blueyonder.co.uk> wrote:
On Mon, 3 Aug 2009 01:09:27 -0700 (PDT), James Kanze
<james.ka...@gmail.com> wrote:
On Aug 2, 10:36 pm, Stephen Horne <sh006d3...@blueyonder.co.uk> wrote:
On Sun, 2 Aug 2009 03:20:04 -0700 (PDT), James Kanze
<james.ka...@gmail.com> wrote:
You're even better off doing things in the correct order:
writing the documentation first (e.g. as cweb, or using a tool
like Rose), and generating the header files from it.
I don't really agree. Sure, planning before coding is a good
thing. But "Rose" I assume refers to the UML tool, and UML is
really just an incomplete visual programming language - only a
bit more complex and confusing to work with than most plain
text programming languages.
UML is a lot more than that---unlike C++ (and most programming
languages) it's a descriptive language.
"class myderived : public mybase" is precisely as descriptive
as drawing one of a range of arrow shapes on a line between
two boxes. Both give exactly the same information - the one
class inherits from the other. Both can only be understood if
you have learned the syntax of the appropriate language. If
that sounds wrong, ask yourself how many different kinds of
relationships might be represented by an arrow between two
boxes.
UML is a lot more than just inheritance (although when multiple
inheritance and virtual inheritance is involved, it is still a
lot clearer than the sources, where all you see is the immediate
inheritance of each class). It's defining how the various
components interact together. More generally, it's a higher
level of abstraction.
UML has some niceties like making "abstract" explicit - but
then, IIRC, so do some other programming languages. Certainly
there's no reason why such annotations couldn't be added to a
programming language. Just as there's no reason why you can't
add a comment to say the same thing in C++ source code. A
Doxygen comment would be the perfect place IMO.
A relevant paper...
http://martinfowler.com/articles/newMethodology.html
Particularly the "Separation of Design and Construction"
section, in which Fowler points out that...
The problem is that Fowler doesn't really know much about what
he is calling the "engineering methodologies". His discription
of them, at any rate, doesn't correspond to anything I've seen
in well run organisations. (Although I don't doubt that any
methodology can be misused, or misinterpreted.)
"The problem with a UML-like design is that it can look very
good on paper, yet be seriously flawed when you actually have
to program the thing."
That's why you have design reviews. The same thing holds true
at all levels---a piece of C++ code can look very good on paper,
but can cause the program to core dump when actually run.
In the end, the basic principle dates from at least Dijkstra.
You start at a high level, without worrying about the details,
and work down. At each level, you are concerned with that
level.
This from the author of the "UML Distilled" books, and it fits
my experience WRT all heavyweight design methods.
UML is NOT a heavyweight design method. It's as heavy or as
light as you want. Or as is needed.
State diagrams, data flow diagrams, entity-relationship
diagrams, class diagrams and all the rest are useful and all
have their place, but as soon as you adopt a specific
methodology and a standardized syntax, you'll end up pedanting
on that instead of the actual design.
Why? Do you end up pedanting on C++, rather than the actual
program? Same principles apply. (Obviously, some people do,
and end up with overly complicated systems. But that's a
problem with the people, and the process, which allowed them to
do so, and not with the notation.)
Basically, you end up putting all your effort into
implementing the methodology and putting all the dots and
commas in the right places in the methodology deliverables,
which is not the same thing as designing your product. And you
end up with something that simply isn't a good design given
the constraints of the final implementation language.
One advantage of UML (as opposed to C++) is that you don't have
to worry about all of the dots and commas. It's a very open
language, since (at least large parts of it) are really only
read by people, and don't serve to generate machine code
directly. (And I'm tempted to say that if at the higher level,
the design doesn't fit the language, and the design was well
done, you should change the language. But C++ is pretty
flexible, and I've yet to find a design which it didn't fit.)
[...]
"These kinds of questions led Jack Reeves to suggest that in
fact the source code is a design document and that the
construction phase is actually the use of the compiler and
linker. Indeed anything that you can treat as construction can
and should be automated."
And this again fits my experience. Everywhere I've worked, the
primary source of design documentation was always the source
code, for me and AFAICT every other programmer. Any other form
of documentation is always outdated and misleading. Even
comments can get outdated and misleading.
Then you've never worked in a well run shop. The code is
reviewed against the documentation, and when changes are
necessary, the documentation is updated before changing the
code. In one case, the header files were generated completely
from Rose, and were treated as a derived object, which couldn't
be edited. More often, however, there was almost nothing in the
header that was edited, and in the same way you currently edit
the header and the source file, you'd edit the UML diagram and
the source file. With the difference that the UML diagram was a
lot more readable, and a lot easier to edit correctly than a C++
header file.
The best design documentation I've ever had access to is a
subversion repository. Either that, or the
back-of-whatever-scrap-paper-was-handy doodle that somehow is
still the primary reference a year later.
The problem with not having such tools (e.g. Rose) is that you
use some sort of graphic abstraction anyway. With Rose, it's
UML, and it's in the machine, where others can access it, review
it, and refer to it later. Without some such tool, it's scratch
paper on your desk, and it gets thrown out before you're
finished coding. (At least, that's been my case. I have heard
of people using a white board and a Poloroid camera---this was
before digital cameras.)
And if you don't like UML, what do you like? You do need
some way of describing how the pieces fit together.
Yes you do, and diagrams can do that. The diagrams that
Doxygen give me are UML diagrams,
But they're not complete (there are relationships that they
don't show, and there are no scenarios---in my experience, one
of the most important diagram types).
but I'm not the one pedanting on the syntax details - Doxygen
is.
There are more semantic details in the C++ code than in UML
diagrams. (Note that tools like Rose need to maintain
additional information, entered in various dialog boxes, in
order to "generate" the C++.)
Though it says something that the situation is just like it
was for me 20+ years ago, when anyone wanting a decent grade
rewrote the design documents from the source code before
handing in their work. These days, the only difference is that
a software tool does the rewriting for me.
And in the companies I've worked in which used Rose, it was Rose
which did the rewriting in C++.
And before you say it, yes, I agree that in itself Doxygen
cannot write design documentation - everything depends on the
comments. But then I've always written a lot of the comments
before I write the code. It just means that now I write most
of them as Doxygen annotations.
In my case, I write my comments as plain text (or simplified
HTML); I have a program which formats them into Doxygen
annotations (and since I use vim, it's no problem to switch to
text mode for the comments, then run the results through my
program). And the comments are written first, before I'll write
the code. But such comments can't cover everything. The header
file is the ideal place for detailed comments concerning a
single class or function, but where to you put more general
comments, concerning the relationship between several classes.
Or the scenarios; the time line of what happens (or would have
happened, if the code worked) for a given transaction.
A lot depends on what level you're working at. In my library
code, I don't really miss Rose that much---it's mostly a case of
one class doing a simple, specific job, and the essential things
to know are the pre- and post-conditions for each function, and
any class invariants. Even in some of the more complicated
cases, which a number of classes, the relationships are simple
enough to explain in plain words (a parse tree, with different
nodes having different derived types, for example). In my
business software, on the other hand, it's not unusual for a
single transaction to involve twenty or thirty different
objects; a clean graphic representation of the relationships
among these objects, and a couple of clear scenarios for typical
cases, make understanding much, much easier.
Of course, as always, more than a few comments get deleted
later because the code says it better.
It depends on what code. How does the code say that the vector
passed to a particular function must be sorted? (On the other
hand, I did once work in a place which required that every
function be documented with Doxygen-like comments, with a number
of required fields, like behavior, and one for each parameter.
So you ended up with something like:
// setAdministrativeState:
//
// \behavior
// Sets the administrative state to the
// new value
//
// \parameter newAdministrativeState
// The new value.
//
// \post
// getAdministrativeState() ==
// newAdministrativeState
//
// \throws
// Nothing.
// ---------------------------------------------------------
void setAdministrativeState(
AdministrativeState newAdministrativeState ) ;
I've yet to have met a programmer where the function signature
wouldn't have been enough:-). Even the post-condition is
implicit, given the name and the naming conventions in effect.
About the only time any comments would have been justified here
is if setting the administrative state had some other side
effects not implied by the pre- and post-conditions of other
functions. (Note that this was before the days of syntax
hilighting, or even color screens, so the // ---... line was
necessary to clearly separate the comment from the code. I'll
admit that I've gotten so used to it, that I still use it, even
though the comments in my editor display in a different color
than the code.)
There is no one right answer, but in this particular project,
Rose would have been a lot more helpful than all of the
Doxygen-like comments.
I also often have diagrams before the coding starts, of
course, using simple, often ad-hoc conventions, making sure
that the meaning is clear without a three week training
course.
Guess what? I've never had a course in UML (or Booch, which is
what I started with). I only recently read my first book about
it. That never stopped me from using it, and Rose. (It took me
less than ten minutes to learn enough Rose to use it for what I
was doing. It took me maybe ten years to acquire a similar
level of fluency in C++.)
When it comes to deciding the details, I decide them in C++ so
that they'll work in C++.
Your false assumption here is that it is impossible to
understand the structure of a design without adopting some
heavyweight methodology like UML.
Your false assumption is that UML is a heavyweight methodology.
It's not; it's a lot easier to work in and understand than C++,
because it's a lot more forgiving (except for the parts that are
actually used to generate the C++), and it's at a much higher
level of abstraction.
I would argue that you have things backwards - when it comes
to understanding a design, heavyweight methodologies and
overcomplex visual representations that require whole books to
list all the various distractions - sorry, details - are the
problem, not the solution.
Maybe. I've never encountered any such methodologies, however.
--
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