RE: Comments

[Danny Ayers <danny@panlanka.net>]

<- XML 1.0 comments work in both DTDs and documents, and commenting
<- any kind of
<- code is always a Good Thing, and people rarely use it as much as they
<- should.

But what about the Xtreme view of good code being self-documenting? - if
your code needs comments then your naming/structuring is at fault. Ok, this
*is* the extreme case, but it's a reasonable point - you should be able to
tell what a thing is/how to use it/if it bites without needing a manual.


I've seen programming books that encourage you to
<- comment your code
<- and then don't comment their own code samples.

hee hee - I've just been caught out on that one - I felt that the comments
were better in the body text as proper human language, but several tech
reviewers disagreed - consider me reformed...(for the moment ;-)

 XML 1.0 comments are for
<- whatever you want them to be for; for example, if I write something that
<- generates XML output, I usually start that output with an XML
<- comment that
<- has a time stamp, the name of the generating program, etc. In an XML
<- document that I'm hand-editing, I'll have a comment that shows
<- the last date
<- edited andmaybe a to-do list concerning the work I'm doing on
<- it. It's also
<- a place to store version control information for use by a
<- package like rcs.

These are noticeably time/version control related (where change is
anticipated), rather than 'static' content related. Could that be
significant?