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

[Jose L. Z. <jlz...@ca...>]

El Mié 26 Sep 2001 10:35, escribiste:
> Hi Jose and others,
>
> 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.

	**** Yes **** this is the question. If doxigen scan inside the functions and 
recongize the keywords (for, if, while, switch) I don't need worry about the 
indentation.


>
>
> An algorithm is only a part of the solution.  

	OK. ¿ It is not importat to show it in documentation ?

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

	OK. I agree. But ** also ** is important.
>
> 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.

	100 % OK But when you have problems any help is good.


> Each change in the abstract view may cause changes
> of those details.  

	OK but the "details comments" are just near the code. You need to be a beast 
to no correct the situation and comment the changes.

> 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.
>
	OK but when you have problems... You need see the code. And I don't want 
this.

> The ** how ** is not that much important here if
> you know that it is possible ** somehow **.

	are you sure ?
>
> > 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.  

	If you have documented ** what ** and ** how ** you don't need see ** how 
**. But if you have problems you need ** how **

	If you are a teacher, ask this questions to your students?

	What happen if you have a undocumented or insuficient documented code ?

	Result = Smoke in head by reading the code.

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

	Because the comments inside the functions are important * only * when I have 
problems and read the code is a waste time if the code are writed by a 
programmers team.


> >
> > OK ;-) I am a newbie.
>
> ;-) Don't take me wrong.  I am not your teacher,
> and you are not my student.  

	Why not? I like learn.

> We are absolutely equal
> here.  I am also learning by reading the ideas
> like yours.

	I am a experience programer and I find doxigen after write many code lines 
and many unlinked documents. I like doxygen. It is also I search.

Thank you very munch. It is very instructive.


-- 
José Luis Zabalza
jlz...@ca...
Linux User 172551