Re: static inline functions - possible?
On Aug 7, 1:23 pm, Stephen Horne <sh006d3...@blueyonder.co.uk> wrote:
On Thu, 6 Aug 2009 01:55:10 -0700 (PDT), James Kanze
<james.ka...@gmail.com> wrote:
I'd say you're looking at it backwards. What I like about
UML is that I don't have to be concerned with the pedantic
aspects of C++ when I'm using it. I'm working at a higher
level of abstraction. With some formalisms, but a lot less
than are present at the lower levels.
You don't have to pedant all the details of C++ to write
comments, or the initial not-meant-to-compile,
not-meant-to-be-even-nearly-complete drafts.
Agreed. I use that too. I also use HTML, for information that
transcends single files, and is best expressed in text, rather
than graphically. I find, however, that the graphics of UML are
more expressive than plain text when it comes to expressing the
relationships between classes, scenerios, and such.
There is one other aspect, where tools like Rose seem to be in
advance of the text based tools I use. What you're writing
isn't just a rough draft---it's meant to be read and maintained.
And one of the things that has always bothered me with most
forms of documentation is that the "source code" of the
documentation, which is what the maintainer has to deal with,
isn't as clean and neat as the documentation itself---CWeb
sources contain distracting mark-up, Doxygen comments have all
those comment markers, etc. This seems to be less true of Rose,
in which what you see is what you get, with regards to the
documentation. (For the graphics, at least. Not all
documentation and design can be expressed with graphics, and the
integration of text in Rose---or Together---cannot be considered
particularly successful.)
For Doxygen comments, I've written a couple of tools, which work
well with my editor (vim)---when I want to write a comment
(Doxygen or not), I'll hit F1, which changes the mode of the
editor so that the programmy things are turned off. I'll then
write the text as I would in a plain text document, with some
very simple (not very well designed) mark-up. Finally, I'll hit
F2, which pipes the text through my program, formatting it as
comments (Doxygen or not, depending on the options I add), and
puts the editor back into C++ mode. When I want to edit the
comment, I also have a command which converts the text back into
its original text form, more or less; I then edit that, and
reformat it as a comment.
Another aspect in favor of Rose or Together (compared to the
other tools I know) is that they understand much of the
structure. You modify the name of a class, for example, and it
is modified everywhere, in all of the diagrams. Global search
and replace can do a lot of that with a good editor, but it's
not quite as effective.
To use an analogy, there are all sorts of writers guides out
there for people who dream of writing a novel. There's
software tools that prompt for and organise details of
characters, settings, events and so on.
The professional writers most certainly have methods, and
maybe a few even use Writers Cafe or whatever, but it seems
that what really works is the quick draft followed by repeated
ruthlessly critical rewrites. Anything beyond that and ad-hoc
notes is a newbies magic non-solution or the occasional pros
personal quirk.
In short, the approach doesn't require different notations.
I've already admitted my error and I won't claim that UML
isn't a valid and appropriate option, but this doesn't mean
that a process of quick drafting then ruthlessly critical
rewriting cannot be done in text files that will eventually to
be fed to a compiler.
I don't know how professional novelist write; I suspect it
varies depending on the novelist. (Mozart never wrote anything
out until the final version. Beethovan wrote out endless
preliminary versions.) And I'm not sure it's a valid analogy.
There are too many differences in the product: a program has to
meet very rigorous specifications, for example; it must be
maintained (and thus be maintainable); the design documents
become part of the documentation, etc., etc. A more valid
comparison would probably be with an architect designing a
house, but I don't really know how they work, either. (And even
there, there's no need to document how they came up with the
design for later use.)
As you say, some silly scrap of paper gets lost, used to wipe
up a coffee spill, or whatever. But a scan, or a copy using
some simple diagram or vector drawing tool, is still, in
essence, the same diagram.
More or less. The scan isn't editable, which makes
modifications more difficult.
Actually, I have Photoshop and a cheap graphics tablet, and
there's always Windows Paint or similar and a mouse. For that
matter, almost any vector graphics program can put a scan in
the background, mask areas using white rectangles, etc etc.
You're not going to tell me that that's anywhere near as simple
as modifying a UML diagram with Rose:-).
TortoiseSVN can even show two versions of an image
side-by-side or give you a slider to transition from one to
the other.
And vector drawing tools don't normally ensure coherence,
when several drawings are involved. And neither actually
generates any C++.
This is true - but surely, as soon as you ensure coherence
between diagram and source, you have to pedant about the
notation of and details in the diagram? It becomes visual
source code, IOW.
First, I was principly thinking of coherence within the design
itself. Change the name (or some other characteristic) of a
class, and it changes everywhere, since internally, the system
stores a reference to a description of the class, and not the
visual image.
With regards to coherence between diagram and source, yes. When
you get down to the levels which affect code generation, you
have to be somewhat pedantic. Not quite as much as if you were
writing C++ directly, but almost. But that's no different than
with any other technique---in CWeb, you have to enter the parts
that will end up as C++ source code exactly as C++ source code;
with Doxygen, you're actually writing C++ code. With the other
tools, you also have to be somewhat pedant with respect to the
parts that don't generate C++ code---with Doxygen, to such a
degree that I was motivated to write a tool which takes care of
it for me. I find Rose significantly easier in this regard.
You need some sort of conventions if you expect other people
to be able to understand it. UML is fairly loose---about the
minimum necessary for what it tries to express.
Sometimes, more is less. Less familiar, for instance. Everyone
understands a basic bubbles-and-arrows dataflow diagram, for
instance, but how many people have instant familiarity with
Ward/Mellor conventions, or Yourdon conventions, or Mascot
conventions? How many would know that that other arrow style
is a control flow, or how a control flow differs from a normal
data flow? How many would know that that box with open sides
is a data store, rather than a normal process? How many people
know that dots and bars at the ends of an arrow indicate which
process is in control of the data flow - who calls who, or
which side of a rendezvous or whatever you're on?
And how many people are familiar with your personal conventions.
Your argument here is in favor of UML, not against it. UML is
the most widespread standard diagramming language. It is thus
the one most likely to be already known by others.
Less freedom, too - you can't improvise your own arrow style
for some application-specific purpose without having to check
that you're not using an already-standards-defined special
purpose arrow and therefore causing confusion, or having
pedants tell you "you can't do that - it's not in the
standard" and getting too stressed about your blasphemy to
focus on the design itself.
People do:-). People also invent new words in English, or give
existing words different meanings.
It's all a question of whether you want to be understood or not.
Inventing some new arrow style, or word, for some special use,
is not something to be done lightly, since no one reading the
document will understand it.
Consider a state diagram. You have boxes and arrows, write
"xxx state model" at the top, and everyone understands it. Use
the UML standard with it's three-part split boxes and suddenly
only the UML-familiar are confident they know what the
different parts express. It's not just a state model any more
- it describes implementation details and thus references an
implicit implementation model which readers need to be aware
of.
It doesn't have to.
I didn't use state diagrams much in the applications where I
used Rose, but given the way other nodes (classes, etc.) are
handled, I expect that in any diagram, you can mask out the
information irrelevant to that diagram. And you're never
required to enter information that would be irrelevant to all
diagrams.
For example, there's a built-in assumption that the states
relate to a particular class. The first edition of "UML
Distilled" has eight pages describing UML state models (one of
the simplest UML diagram standards), and the first paragraph
places arbitrary limitations on their use seemingly without
even noticing - an abstraction for which a state model applies
*MUST* be a class.
As I say, I'm not too familiar with state diagrams, but I can't
find this restriction in any of the documentation I have.
Fowler (in UML Distilled, Third Edition) actually mentions three
possibilities: nested switches, the State pattern, and state
tables. (But I don't know what Rose does with them, if
anything.)
Split your boxes into three for some application-specific
reason - maybe every state has three outputs - and, no matter
your key or the explanation that makes sense to everyone else,
the UML-familiar readers will be thrown. And your tool will be
very upset, of course.
Throw in enough German words when writing English, and your
reader will become confused. What's the difference?
So yes, you need some kind of conventions - but simpler is
better. The cost of more complex standard is that the extra
notations you use are unfamiliar to lots of readers, while the
notations you don't use get in the way of expressing ideas
that the standard didn't anticipate.
UML could be a lot simpler, but generally speaking, you don't
have to use all of the extra features. UML diagrams are only as
complicated as you want to make them.
Interesting. I think that most of my Doxygen documentation
is in the form of \pre, \post and \return. In a lot of
cases, \pre and \post effectively describe all of the
behavior of the function; in the case of "true" functions
(with a return value other than just a return code), the
\return more or less replaces the \post (and unless otherwise
documented, there is an implicit \post---that the object is
unchanged by the function).
Preconditions and postconditions are easily documented in the
detailed description. I never even looked for those tags. I
have no objection to them - I just happen not to use them
myself.
Everything can easily be documented in the detailed description.
There are some advantages, however, to using standard
tags---they create a standard formatting, so the reader can
easily identify them.
I prefer the 'const' keyword for saying the object is
unchanged, though if you meant side-effects or changes to
mutable members, I agree with the basic point.
Agreed. I just picked the first example that came to mind of
something that doesn't need explicit documenting, but you're
right, in C++, the language itself documents that. (With
regards to mutable members... they should be an implementation
detail. If the modification of a mutable member means that the
"value" of the object is seen to change by a client, then any
function which does that modification should not be const.
Mutable is for handling internal details, which the client can't
see.)
--
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