Ralf Hemmecke wrote:
>
> > I shortened comment for 'prodiag1': most of the comment was writing
> > the same thing as code only in different notation.
>
> Well, I'm not so happy about this. I'm still having the opinion that
> code is no documentation. My documenation contained a *derivation* of
> the program code. Why do you dislike that so much that you remove it?
>
> For someone to convince himself that the code is OK, he would have to do
> exactly the same derivation. Of course, a person who is interested in it
> should be sufficiently smart to be able to redo my derivation, but why
> does it make sense to let those people reinvest time if the
> documentation was already there? You did not even have to write it yourself.
AFAICS this was not a derivation. The line
concat(frst(f1), rst(f1) + p1 + concat(rpSt(n, 0), f1*p1))
is a recursive formula written using Spad. It refers previous
definitions of f1 and p1. You wrote the same formula but
using different notation. This formula has a derivation.
Derivation is simple, so it is better to omit it (as I and _you_
did) -- reader can easily reconstruct it.
This kind of comments help if reader is unfamiliar with Spad,
but otherwise just adds bulk to the file. Bulk is bad because
every reader will spent more time reading and internalizing
what was written. Note: I expect that active and interested
reader will re-derive the formula. Adding more detail will
not help and may hurt turning the reade to "passive mode".
To put is differently: your addition would be good in a
tutorial. But I bet that reader facing substantial amount
of code with such documentation will quickly give up
due to bulk of text to read. Some readers will learn
Spad and used conventions and for them extra text will be
tiring. Other will give up deciding that the whole thing
is too hard.
Spad notation is closer to usual math notation than several
other programming languages. You may think that in other
systems should be much more pressure for such explanations.
Yet practice shows that people cope quite well. When I
was teaching introductory programming course given task
"turn this formula(s) into code" or even "what this piece
of code is doing" students did quite well. So given
clear code there is little need for line by line
explanations. People may have some trouble to find
solution given a set of recusive equations. So it make
sense to state what 'prodiag1' is computing and in
general it make sense to state various invariants.
But in general IMO we need explantation of math behind
code. Not at line-by-line basis or even routine-by-routine,
but general properties and algorithms in use. If you get
background math tracing code is not that hard. It may be
tiring because of various details. But extra detailed
explantations do not make is realy easier because of
_larger_ amount of material to trace. OTOH without knowing
math code can be misterious. But explaining lower level
details without explaining higher level does not really
help. So I want to have more documentation, but apparently
different documentation that you would like to write...
Concerning "code is not documentation": look at Bronstein
article about RDE:
Manuel Bronstein, The transcendental Risch differential
equation. J. Symbolic Comput. 9 (1990), no. 1, 49-60.
Substantial part of article consits of (pseudo)code, and
parts stated via code are _not_ duplicated in text. While
one may wish more explanations, actually, if you read earlier
Rothstein thesis (which Bronstein cites), then code
is quite readable.
--
Waldek Hebisch
[email protected]
--
You received this message because you are subscribed to the Google Groups
"FriCAS - computer algebra system" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/fricas-devel.
For more options, visit https://groups.google.com/d/optout.
