Re: Antwort: comments. (Re: key() Re: Saxon VS XT)

----- Original Message ----- 
From: <v.rudowitsch@xxxxxx>


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