From: Mark Probert Date: 2004-09-01T03:10:24+09:00 Subject: Re: Typos (Was: performance comparison) Hi, Lothar. Lothar Scholz wrote: > > And so my argument is that this is not valid example that the literate > programming modell works. > Backing up a little, and leaving the words "literate programming" aside. As a coder, I assume that you use comments in your real-world code. As an experienced real-world coder, who has done some maintenance work, you would also have come to appreciate the value of other peoples' comments. Often the more the better, particularly in those "optimised" sections. I also assume that you have discovered that if you use RDoc or Doxygen or similar, you can have comments in your code formatted nicely. You produce your detailed implementation documentation as you go. It save you a lot of time in the long run, avoids having to go back and work out what you did when it was time to document your code at code review time. The reviewers are happy. Your fellow coders are happy. Managment is happy because they realise that your production code will be supportable from India. You get the idea. So, where do you think this "code + documentation = Good", comes from? Does it help to reduce maintenance costs? My experience says yes. Empirical evidence seems to support that conclusion as well. Is it taught in universities etc.? No. Does it make "real world" sense? Yep. Is it used within my organisation? No. Should it be? Yes. How come? 'Cause coders, code, they don't write documentation. 'Cause, on the whole, those writing the code don't have to maintain it. "A rose by any other name ..." Regards, -- -mark. (probertm @ acm dot org)