Re: Documentation, Literate Programming and the Real World

[sur-behoffski <sur_behoffski@...>]

Sean O'Connor wrote:
>>                  /* Have we reached the end of the pattern?  */
>>                  if (pPat == pPatEnd) {
>
>  Again, this comment is just mimicking the code (you picked good names, so
> points for that).  Also, why not?
>
>	 while (pPat == pPatEnd)
>	 {
>
> instead of the infinite "for() if" combo?

(Yeah, I know you meant (pPat != pPatEnd)... okay.)

The stripped-down version of the code was so sparse that it did not show
other cases where the loop might be broken in unusual ways.  I *do* write
conventional for, do and while loops, but only if the top statement
fully covers the body's behaviour.  As soon as there was more than one
way to exit the loop, I refused to choose any of the possible
"conventional" constructs as the apparent loop control, and instead
used "for (;;) {" as a warning to the reader.

This is a style that I developed during the '80s.

--

Ironically, I've started looking at the reverse situation, due to looking
at OpenMP C code (in IM/IUP/CD, no less), and there, the converse is true:
You need to write an explicit loop, are *not* (asynchronously) allowed to
break out, but still can do things like "continue" inside the loop.

More recent versions of OpenMP have added "cancel" and "cancellation point"
constructs, so that asynchronous termination can be handled more neatly.
The original loop still needs to be written explicitly, so that the
compiler and/or the various runtime libraries and/or pragma hinting by the
programmer can feed into the decision on how to break up the workload
amongst members of the available thread pool.

--

And just briefly, one comment of yours that I strongly endorse, and would
have mentioned it if I'd remembered:  The "line-preceding-paragraph"
comment always strives to be written at a higher level of abstraction than
the underlying code itself.  Thank you for reminding me of this in your
feedback  ("I tend to comment why I do something, rarely how I do
something.").

cheers,

s-b