Re: Documenting my project
On Jul 14, 5:35 pm, Rui Maciel <rui.mac...@gmail.com> wrote:
Erik Wikstr=F6m wrote:
There are a lot of tools available to create documentation from tags
embedded in the code, Doxygen is on of them. However if I were you I'd
focus on documenting the high-level design of the project rather than
what each function does (even tough it's nice to have that documented
too). The reason is that any competent programmer can figure out what a
function or class does, but you don't want to learn how all the
components work if all you want to do is to make a small change. Given a
good documentation of the higher levels of design makes it easy to find
the places where to make the change and you can then get the job done
much faster.
Indeed. Moreover, doxygen-type documentation is only helpful when dealing
with code which, for a programmer to integrate it in other projects, he
needs some sort of detailed reference to be able to work. To put it
simpler, libraries. In other circumstances that type of documentation can
be a bit useless, not to mention that it will not offer any added value
when compared with any IDE out there.
Not to mention that there is still the risk that the
documentation and the code don't agree. A little less, perhaps,
because the programmer doesn't have to open a new file to modify
the documentation, but not very much less. (A good process will
prevent this, of course---the code will be reviewed against its
documentation, and won't be released until it is conform.)
Having in mind that the message was posted to a C++ newsgroup
and assuming that the code follows some OO methodology, I
believe that those who wish to read and understand the code
are better served with some UML-based documentation. Even if
it only covers higher-level stuff, I believe that it will be
more useful than any detailed, doxygen-like documentation.
At least at the application level, some UML documentation, or
something equivalent, is definitly necessary. Once again,
however, if the documentation is separate from the code, and
after the fact, there is a risk of the two not agreeing. Most
UML tools can be used to generate the code, or at least the
headers, and this feature should be used. (There's still no
guarantee, of course, that the code might actually depend on
some undocumented pre-condition, so even this doesn't dispense
with good code review.)
That will enable anyone to get their head around the general
structure of the thing and then the code itself will do the
rest of the talking.
It will also help the author to understand what he is doing.
One real problem that I see with C++ is that most of the really
good authors are involved mostly with low level code, basic
libraries and such. Low level libraries tend to contain a lot
of more or less individual classes---the STL does try to tie
them together somewhat by means of common concepts, but this is
still not the general case. So the necessity of high level
structural documentation (and design) is often ignored. Most
actual C++ programmers, however, are probably working on
applications, where most classes work with or are associated
with other classes in some way, and such documentation is
absolutely critical.
--
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