On Thu, Sep 11, 2014 at 05:46:22PM -0400, James K. Lowden wrote:
[ ... ]
> If by "all about" Urich meant a sentence or two, sure, a comment block
> is fine. If by "all about" he meant a description of the semantics of
> the public interface (which is what I thought he meant) then ISTM that
> belongs in a manual, not in the source code. N'est-ce pas?
>
I was NOT referring in any way to semantics or public interface, but to the
inner
workings of the implementation and how to make it understandable to a later
maintainer
(or to the original programmer after a few years).
That should have been clear from the previous discussion on programming style.
To give an example:
The seemingly trivial string searching function strstr() can be implemented
using
sophisticated algorithms like Rabin–Karp algorithm, Knuth–Morris–Pratt
algorithm,
Boyer–Moore string search, ...
Their description belongs NOT into the man-page (though a hint about the
time-complexity would be nice).
But to understand the source code would be impossible without explanations and
pointers
to the relevant literature.
ulrich
