RE: [Doxygen-users] [Large] Algorithmics comments or comments ins ide body functions.

[Prikryl,Petr <PRI...@sk...>]

Hi Jose and others,

Jose Luis Zabalza wrote:
>
> Petr Prikryl wrote:
> >
> > Jose Luis Zabalza wrote:
> > > I come back again about the idea of ** what ** do
> > > a function or ** how ** do the function his work.
> > > I believe is important the documentation show two
> > > things.
> >
> > On the other hand, any function should be on a
> > bit higher level of abstraction than the things
> > inside the body. [...] While
> > you may want to extract some points about how the
> > function works, for me it is much easier to
> > sketch the idea more roughly in the comment
> > outside the body.
> 
> OK. I think so. It's all right. But, when you have
> hurry up is very easy forget the generic abtract
> comment but it's easy to write a little coment
> near the for keyword, or near the if keyword or
> near the return keyword.

I think that this is quite important point.  My
view is that you should never hurry so much ;-)
Otherwise, it finally takes more time than going a
bit more slowly.  

One more notice here; when I wrote about higher
level of abstraction, I was not thinking only
about describing the existing commands in human
language.  I meant also to decrease "the complexity
of the description" by, say, collapsing loops and
branches, etc.

See other comments below.

> > If you want even more details, you can use
> >   INLINE_SOURCES = YES
> >   SOURCE_BROWSER = YES
> > in your Doxyfile.
> 
> Yes, but this is very noisely, it is more descriptive :
>         
>     - This.
>     - If this
>         - this.

One problem is that when polishing the approach,
you may finish with another (description) language
with your own syntax -- i.e. something that
increase the complexity of your work.  Look at your
indentation notation, for example.  

    # A algorithmic comment has the format :
    #
    #           // <(.*)> Algorithmic comment.
    #           // comment continuation.
    #              until a no init comment line.
    #
    # Where (.*) can to be :
    #
    #    <>   : Algorithmic comment init.
    #    <+>  : Algorithmic comment init indent +1 position.
    #    <->  : Algorithmic comment init indent -1 position.
    #    <-n> : Algorithmic comment init indent -n position.


You have to type more characters, and (what is
more important) you have to think about what you
are expected to type.  You have to take care to
get the good result.  Rather exagerating, you are
writing another program in parallel.

> When you design a program. What is the first think
> you do ?

I think about "the problem". ;-)

An algorithm is only a part of the solution.  Data
structures (also the dynamic ones) are another
part. The cooperation between the parts of the
application is also important.  When you are fixed
to some algorithmic view at very early stage, you
may loose the global view to the solution.

The object oriented programming and design is the
result of also such observations.  One should
decompose the problem very carefully, not thinking
about implementation details at the beginning.
Each change in the abstract view may cause changes
of those details.  If you put too much work into
designing the details, you may feel sorry later to
throw it away, and this, in turn, may break the
search for better solution.

One should start to decompose the problem from the
top to the bottom, hierarchically (once known as
top-down design, but mainly from the algorithmic
point of view).  One should preserve clean
interfaces between the parts (no dirty dependences
on some internals of the solution) -- I am
thinking about the abstract view here, not about
typing the source.

One should continue to decompose until you reach
some level where you know that the part is
implementable, self-contained.  In other words,
you do NOT know ** how ** excactly it will be
implemented, but you are somehow convinced that it
is possible to implement it.  You must know 
** what ** it should do.

... and this is the key point.  This should be
documented.  This gives you some some global view
of the problem.  And this should also be the case
when documenting functions, especially the member
functions (i.e. object or class methods).  
The ** how ** is not that much important here if
you know that it is possible ** somehow **.

> I think in a algorithm. After I encode this
> algorithm. And if I have some time, I document the
> program. This is wrong. Doxigen help me to write
> the documentation near the code, so I write the
> documentation at same time.

I have observed many times that programmers
(students in my case) often tend to explain their
project in say "algorithmic way" like:
  
  "If this holds, I do that.  Then if this is the
   result, I do this..."

It's because they think this way when implementing
the solution.  They know ** what ** they are implementing.
But for other people---and even for other programmers 
(students) who do not work on the same project---this kind
of explanation brings too much details and do not
give some global overview of the problem.  My
personal experience also is that after 2 or so
months (doing other things) you will be in a
position of "the other" person.  You will look at
the code that you wrote and you will try to
understand "Why is this done this way?".

In my opinion, writing good comments inside
function body is necessary to avoid such problems in
future.  But the question is whether you want to
extract them to the documentation.  Usually, you
need the comments inside the function body only if
you are really interested in understanding
details.  Probably, you are going to modify the
function.  Probably, you do it when you are
programming, looking inside sources.  It is
unlikely that you will want to do it through 
looking at the generated documentation.

The documentation must be much more brief
and somehow much different.  We should 
take advantage of the human ability to
understand also rather not mathematically-precise
descriptions.  The long, machine-oriented (or
mathematically accurate) descriptions are not
always better for humans.

When you extract the steps from the function body,
it is likely that the result will look very machine
oriented.  It will never be one sentence that will
describe the problem being solved.

> > Once your project and documentation gets bigger,
> > you will appreciate other features than digging
> > out as much details as possible.  The opposite
> > may be desired.  If the printed documentation
> > would have 2000 pages, nobody would ever read and
> > study it.  
> 
> OK. It is posible, hide or show algorithm coments.

Then, if you finally hide it, why do you want to
generate it?  Only to work with "sources" through
the documentation?

> > I went through the
> > same stage as you are going through now -- so I
> > think that I can speak about having such
> > experience.
> 
> OK ;-) I am a newbie.

;-) Don't take me wrong.  I am not your teacher,
and you are not my student.  We are absolutely equal
here.  I am also learning by reading the ideas
like yours.

Regards,
  Petr

-- 
Petr Prikryl, SKIL, spol. s r.o., pri...@sk...