[
Lists Home |
Date Index |
Thread Index
]
David Megginson wrote:
> Simon St.Laurent writes:
>
> > Second, that kind of markup is only useful until we can't find the
> > documentation any more. For cases where the documentation is always
> > going to be absolutely positively necessary, maybe that's fine.
>
> Apologies if this point has already come up (and I've missed it), but
> it's worth noting how the software world has been creeping towards
> integrated documentation in source code for some time. There were
> many early models, such as Knuth's Literate Programming, documentation
> lines in eLISP functions, and Perl's POD, but integrated API
> documentation really seized the collective imagination of coders with
> JavaDoc, something is now much imitated in C++.
>
> In theory, there is no reason that API documentation cannot be
> separate from the programming code; in practice, (a) it never gets
> properly maintained and updated, and (b) as Simon mentions, it often
> gets lost. The same thing lesson to XML -- making an XML document
> partly self-documenting is always a good thing.
just musing...
Database theory makes a pretty strong case that redundance in functionally dependent data elements leads to update anomalies. In practice, this is the case even when a development organization makes strenuous efforts to properly maintain and update the documents. Either the code or the document breaks, or both, on a more or less regular basis.
That's also why distinguishing uses like
<ProductPartIdentifier UID="9_5.8">123-456-789</ProductPartIdentifier>
from
<UDEF_9_5_8>123-456-789</UDEF_9_5_8>
is important. It goes towards whether I can impose my own local editing, processing, and updating processes without recourse to some third party, whether and whose ideas of "universal identifiers" I use in my own systems, and whether or not I can work with someone else whose ideas of "universal" differ from my own.
Regards,
Mitch
|
