> > > Is there a way to have the Help builder pull in the 'header' block
> > > of comments of the code?
> >
> > Hi Charlie,
> >
> > Here's a utility I wrote to do this, below.
>
> Huh. Sounds kind of like Perl PODs.
>
http://perldoc.perl.org/perlsyn.html#PODs%3a-Embedded-Documentation-POD-
documentation
Tiny version: http://tinyurl.com/jm3bo
Any way it's done, the underlying goodness is the ability to scoop up
actual, realtime information from real libraries, as opposed to relying
on more theoretical information from abstractions written outside of the
actual system. Not that the abstractions don't have their place, but
when dealing with understanding, fixing and extending a real system,
it's far better to have an actual "inventory" of what in fact exists
then something written at a 'higher level' which is subject to all kinds
of machinations. Sure, there's always room for error this way too, and
omissions and even deceit, but as we know, more often then not the
typical good programmer will at least put a good faith effort into those
embedded comments - if for no other reason then to remind him/herself
why something was done a certain way.
One thing that bothers me though is the presence of potentially large
amounts of doc embedded in the code (which was why I focused on the
topmost comment block instead of going into the code below), which makes
it very hard to read just code itself. Perhaps a good solution would be
editor buttons to show/hide embedded comments at different levels.
Bill
©2006 Bill Arnold |
