Documenting my project

[Mohitz]

Hi Guys,

I am almost done with my C++ project. Now, i want to document it so
that it is easy for any other programmer to take it from me and add
more features. I am not talking about building a user manual. I just
want to do documentation so that it the programmer taking the job over
from me finds it easy to understand the structure.

I want your views on "What should the documentation ideally contain?
And are there tools available for them?"

TIA
Mohit

 

[red floyd]

Hi Guys,

I am almost done with my C++ project. Now, i want to document it so
that it is easy for any other programmer to take it from me and add
more features. I am not talking about building a user manual. I just
want to do documentation so that it the programmer taking the job over
from me finds it easy to understand the structure.

I want your views on "What should the documentation ideally contain?
And are there tools available for them?"

Well, first of all, you have done things in the wrong order. You should
write your documentation *FIRST*, or at the very worst, in parallel with
your code.

 

[William Pursell]

I am almost done with my C++ project. Now, i want to document it so
that it is easy for any other programmer to take it from me and add
more features. I am not talking about building a user manual. I just
want to do documentation so that it the programmer taking the job over
from me finds it easy to understand the structure.

I want your views on "What should the documentation ideally contain?
And are there tools available for them?"

Documentation is not the thing that makes it easy for the next
programmer to take over. (It is important, but it isn't the key.)
If your program is well designed, the documentation will be
easy to write--give a one paragraph description of each major
component, and a paragraph describing how the components
fit together. If you cannot describe a component in
a single paragraph, then you mis-designed that component
and made it too complex. If your program is poorly designed,
then no amount of documentation is going to make it easy
to understand.

So to answer your questions: the documentation should contain
high level descriptions of the major components of the
program. The only tool I am aware of for producing that
is the human brain.

There are several tools available that will generate
snazzy html layouts and man pages, and I'll just
mention Doxygen. However, it is extremely important
to realize that Doxygen (and any other tool) will just
format the documentation that you have embedded
in your code, so it is only as valuable as the
text that you've written.

 

[=?ISO-8859-1?Q?Erik_Wikstr=F6m?=]

Hi Guys,

I am almost done with my C++ project. Now, i want to document it so
that it is easy for any other programmer to take it from me and add
more features. I am not talking about building a user manual. I just
want to do documentation so that it the programmer taking the job over
from me finds it easy to understand the structure.

I want your views on "What should the documentation ideally contain?
And are there tools available for them?"

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.

 

[Rui Maciel]

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.

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. 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.


Rui Maciel

 

[Rui Maciel]

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.

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. 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.


Rui Maciel

 

[James Kanze]

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.

 

[Puppet_Sock]

"What should the documentation ideally contain?
And are there tools available for them?"

Think what it will be like for you six months or
a year, or five years, from now. You get called
back to work on this software. The gizmos it is
supposed to work for have been re-issued with the
new "go faster stripe" feature and you need to
re-do the whatsit.

What would you need to make recalling things easier?
In particular, any tricky areas, or whacky coding,
or obscure things you've done should be explained.
If you had to do something strange to work around
some deficiency of a compiler or library, for example.
Or if you had trouble with some interface or something.

As at least one person said, you're doing it backwards.
Certain parts of the documentation should come before
you have a line of code. A spec is nice. What the code
has to do in order to be considered acceptable is nice.
What constitutes input and output, and when they are
acceptable.

The major features and program flow.

Dependancies on non-standard libraries should be listed.

A listing of non-default compiler settings used.
Socks

 

[red floyd]

Think what it will be like for you six months or
a year, or five years, from now. You get called
back to work on this software. The gizmos it is
supposed to work for have been re-issued with the
new "go faster stripe" feature and you need to
re-do the whatsit.

As at least one person said, you're doing it backwards.

That was me. Having had to do it backwards, because the PDL/SDDD was
specified as a deliverable, and the design docs were not kept up to date
was a pain. We spent three weeks in an orgy of reverse engineering.

 

[Puppet_Sock]

Puppet_Sock wrote: [snip]

As at least one person said, you're doing it backwards.

That was me.

I should have given credit. I was lazy. Mea culpa and
I apologize.

When I was younger I was just as bored and uninterested
in documentation as the next guy. The spec? Feh. The
coder's manual? Feh. We don't need no stinking manuals.
I know what's in my code.

Then I got on a project where I was actually going to
be paid. And the client was actually going to insist
that the software have some particular set of abilities.
And that they be able to maintain it when I was gone.
And that it be done on time and satisfy their needs.
And that the users be able to use it, and train new
users after I was no longer there.

And, Lo! I became a believer in certain aspects of
project control. You make a spec before you start.
You set a schedule. You do some "Hollywood Interface"
design. You create some test cases and use cases.
You make some of the more fundamental architecture
decisions, such as how files will be arranged and
so on. You make resourcing plans. You make plans for
how things will be reported to see that you are on
track to finish on schedule. Yada yada, all that
tedious boring stuff that most people hate.

And one rather wonderful thing I experienced for the
first time, and highly recomend for anybody who wants
to write good software, but hates all that QA stuff.
Get a project manager. That's not a "pointy haired
boss." That's a guy who knows how to do all this
schedule and spec and reporting stuff. So I got
together with this guy about once a week. And he
had all these fill-in-the-blank questions ready,
and he updated the schedule, and filled in the plan.
And he knew what all the charge numbers were, and how
to ask for resources, and who had to be informed
when a version rollout was going to happen, etc.,
etc., and tedious etc.

And *HE* made the report for the pointy haired boss.
I had to talk to the PHB exactly three times on a
one year project. Bliss!
Socks

 

[Mohitz]

Puppet_Sock wrote: [snip]

As at least one person said, you're doing it backwards.

That was me.

I should have given credit. I was lazy. Mea culpa and
I apologize.

When I was younger I was just as bored and uninterested
in documentation as the next guy. The spec? Feh. The
coder's manual? Feh. We don't need no stinking manuals.
I know what's in my code.

Then I got on a project where I was actually going to
be paid. And the client was actually going to insist
that the software have some particular set of abilities.
And that they be able to maintain it when I was gone.
And that it be done on time and satisfy their needs.
And that the users be able to use it, and train new
users after I was no longer there.

And, Lo! I became a believer in certain aspects of
project control. You make a spec before you start.
You set a schedule. You do some "Hollywood Interface"
design. You create some test cases and use cases.
You make some of the more fundamental architecture
decisions, such as how files will be arranged and
so on. You make resourcing plans. You make plans for
how things will be reported to see that you are on
track to finish on schedule. Yada yada, all that
tedious boring stuff that most people hate.

And one rather wonderful thing I experienced for the
first time, and highly recomend for anybody who wants
to write good software, but hates all that QA stuff.
Get a project manager. That's not a "pointy haired
boss." That's a guy who knows how to do all this
schedule and spec and reporting stuff. So I got
together with this guy about once a week. And he
had all these fill-in-the-blank questions ready,
and he updated the schedule, and filled in the plan.
And he knew what all the charge numbers were, and how
to ask for resources, and who had to be informed
when a version rollout was going to happen, etc.,
etc., and tedious etc.

And *HE* made the report for the pointy haired boss.
I had to talk to the PHB exactly three times on a
one year project. Bliss!
Socks

Interesting thoughts! Ya, may be i am following the wrong approach. It
should have
been documented first. But i didnt really have much time. I had to
complete a huge project
in 2 months time. So, i couldn't think much about the architecture and
documentation. I just
did it the way it occured to me.

Is there a software development standard approach that most people
follow?
If yes, where can i find more information?

Thank you,
Mohitz

 

[Victor Bazarov]

[..] Ya, may be i am following the wrong approach. It
should have
been documented first. But i didnt really have much time. I had to
complete a huge project
in 2 months time.

"Huge"? In 2 montsh time? How "huge" is it, really? According to
[now somewhat obsolete] IBM's research, a programmer can produce about
10 lines of debugged code a day, on average, if you take the project
as a whole, from the inception to the release. That makes your "huge"
project about 400 lines of code. OK, even if we bump the programmer
productivity 10 times, you still only have about 4000 lines of code in
the project you can do in two months. "Huge"? I doubt it.

So, i couldn't think much about the architecture and
documentation. I just
did it the way it occured to me.

Programming "as it occurs" is a VERY BAD IDEA(tm). Once you learn
that (and learn the ways to avoid doing that), you'll progress from
a mere coder to a software engineer and beyond.

Is there a software development standard approach that most people
follow?

Ask in 'comp.software-eng'.

If yes, where can i find more information?

In good books. See "Code Complete", "Mythical Man-month", and so on.

V

 

[James Kanze]

Puppet_Sock wrote:

[snip]

Interesting thoughts! Ya, may be i am following the wrong approach. It
should have
been documented first. But i didnt really have much time. I had to
complete a huge project
in 2 months time.

As Victor pointed out, if it's possible to do in 2 months time,
it isn't huge at all. (How big a project has to be to be
considered huge is an open question, but I'd consider anything
less than a million lines of code fairly small.)

So, i couldn't think much about the architecture and
documentation. I just
did it the way it occured to me.

If you don't have time to do it right, how do you think you'll
have time to do it over.

Is there a software development standard approach that most people
follow?
If yes, where can i find more information?

http://www.sei.cmu.edu/. I'd suggest the book "A Discipline for
Software Engineering: The Complete PSP Book", by Watts Humphrey
(ISBN 0-201-54610-8) for starters.