This is the mail archive of the
xsl-list@mulberrytech.com
mailing list .
Re: Antwort: comments. (Re: key() Re: Saxon VS XT)
- To: xsl-list at mulberrytech dot com
- Subject: Re: Antwort: comments. (Re: key() Re: Saxon VS XT)
- From: Paul Tchistopolskii <paul at qub dot com>
- Date: Wed, 09 Aug 2000 07:44:15 -0700
- Organization: The Qub Group
- References: <41256936.002EAEC5.00@seg.de>
- Reply-To: xsl-list at mulberrytech dot com
----- Original Message -----
From: <v.rudowitsch@seg.de>
> > > > I think it is very bad approach to 'solve' the readability problem
> > > > with writing the comments. Code should be self-documenting.
> > >
> > > Well. I supose you can understand "how" but I bet you cannot
> > > find the answers on the questions "why?" and "for which purpose?"
> >
> > As I told, M'r Kernighan's book explains 'why'.
>
> For _all_ problem domains? Then it is really a Bible. :-)))
No, it does not look like a bible. It is a thin book. "Mythical man-month"
is also thin book and is not applicable to _all_ problem domains.
> > Page 27. "Students are taught that it's important to write comments.
> > Professional programmers are often requierd to comment their code"
>
> "If it was difficult to programm, it should be deificult to understand."
Right. It is not more than 10% of the code which is 'complex'.
Functionality implemented by Sebastian's test6 does not look
like it is worth commenting. Or the comment could be:
<!-- "query" | "group by year" -->
query is obviosly self-documenting, 'group by year' requires no
comments if you know the 'pattern'
> Regards!
>
> Vit
>
> PS: It seems an extern documentation with links to templates within xsl file can
> be a solution.
How is it different from Javadoc ?
Rgds.Paul.
PS. XT could be a good reading. Almost no comments, but in presence of
good a-la SmallTalk browser ( Visual AGE IDE ) it appears that having
no comments does not really hurt.
PPS. I'm not saying that "comments are 'evil' - never use them".
Of course, there are situations when you need to write a comment.
( 10% - not more .) Those situations are very rare. 'If it was difficult to write'
in most cases means does not mean 'it is difficult' , but it means
'I have wrote non-obvious code, because I have not tried hard to understand
what I'm writing'. This is not my rule. I of course steel it from one smart man.
This is why perl code should have more comments than any other code.
XSL-List info and archive: http://www.mulberrytech.com/xsl/xsl-list