Re: static inline functions - possible?
"James Kanze" <james.kanze@gmail.com>
It's a question of style, but many people prefer separating
the declaration of a class from the implementation of its
inline functions, to keep the header tidy and clean. (After
all, the class declaration often doubles as a kind of
"reference manual" to the usage of the class, especially in
the lack of better documentation, or if the documentation is
impractical to read.)
Yea, and for many cases the inline implementation documents
what the function does. :)
Perhaps with the help of a few macros:-).
I was thinking of trivial cases, like getters, syntax sugar functions and
such.
Also there are 'rule' functions.
(I'm thinking of the
usual programming by contract technique. I've heard of people
who defined special macros, along the lines of "PRECONDITION()",
"POSTCONDTION()", and "INVARIANT()", and insisted that the
<non-virtual public function be in the class definition, so that
the invocation of such macros be visible. For various reasons,
I've never used this technique, however.)
I was giving it a thought many times, but didn't use in that form. Though
many times I start the function with ASSERT lines (same idea as PRECONDITION
above), it communicates the idea of params or state better than comments,
and 'works' too. Lately I made an extra macro ASSERT_DX,
docmentation-purposed assert, that is intended to remove the content in
release build. Mostly used where the condition is really already checked
earlier, but helps much in reading, and knowing what is left after
elimination.
Where if it wouldn't there are good chances it is not fit for
inlining anyway.
No, it goes with the regular functions.
Headers are good as dox, but you're better off to use doxygen
or like system -- so directly reading becomes only task of who
changes it, the rest can read the derived html, that well
separates&jons the declarations, the code, the attached text,
no matter how it is spread in the source files.
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.
Guess that depends much on the project. I looked at Rose trials around 2000,
did not impress me a bit. And a recent try on AgroUML was way in the
negatives -- the tool does not help at all, but takes away time when I just
want to draw the design I have in mind. Reading back is even worse --
practicly no control over what to show and how. Modification even worse.
Seem we still have to wait long till 'mindmapping' soft meets the modeling
and codegen tools.
And
depending on the tool, it might not easily support such code in
the header functions (Rose doesn't), at least if you want to
make your header files "derived objects", not edited later.
Working with 'wizards' and code generators (mainly MFC-supporting stuff),
left me with opinion, that such code shall be completely write-only. (But
definitely not editable).
I made such a generator translating database to records, relations and all
the stuff -- producing a file for the compiler only, and completely
regenerated on any change.
Well, at that time I did not yet use version control merge tools -- that
could probably deal with an editable file too.
Currently I'd rather see the opposite direction, source browser augmented to
produce all kind of diagrams. (What is actually happening, but have the
same problems: no good change consolidation, if I rearrange the class chart,
adjust it to show/hide the relevant elements, those get washed away. Too
bad.)
I worked with those separated inlines -- at a time made some
myself, my net conclusion is it makes things worse.
It probably depends on what you're doing.
LOL, it ABSOLUTELY depends on that... :)
Putting code in the
class definition doesn't make reading the class definition
simpler, except for almost trivial classes (functional objects,
etc.). Or, of course, if that code really is part of the
"documentation".
In a large project I did recently my policy was that any code appearing
within the class def is just as 'published' as the interface: considered
stable and anyone can build on it as on any other form of dox. (That limits
the options pretty much ;)
Correction: that applies only to normal classes, not to template lib. For
templates I prefer writing stuff right in the class as much as possible,
move out only what is necessary to compile. The policy there is simpler, I
don't expect people to read that header, only the dox.
And if there's a need to read the template the trouble is likely bigger so
source layout is not a factor.
--
James Kanze (GABI Software) email:james.kanze@gmail.com
Conseils en informatique orient?e objet/
Beratung in objektorientierter Datenverarbeitung
9 place S?mard, 78210 St.-Cyr-l'?cole, France, +33 (0)1 30 23 00 34