[XML-DEV Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message]

RE: Comments

• From: Danny Ayers <danny@p...>
• To: Bob DuCharme <bob@u...>, "Al B. Snell" <alaric@a...>,The Deviants <xml-dev@l...>
• Date: Tue, 17 Apr 2001 00:31:26 +0600

<- 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?

• References:
  • Re: Comments
    • From: Bob DuCharme <bob@u...>

• Prev by Date: RE: Massive Cross-Post: The State of XML-RPC, April 2001
• Next by Date: RE: Comments
• Previous by thread: Re: Comments
• Next by thread: RE: Comments
• Index(es):
  • Date
  • Thread