On Aug 31, 2004, at 11:10 AM, Mark Probert wrote:

> Hi, Lothar.
>
> Lothar Scholz <mailinglists / scriptolutions.com> 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.

Seems like Lothar is doing most of his coding in Eiffel which uses 
Design by Contract.  IMHO contracts generally provide good 
documentation and as a bonus the coder writes the contract.  Also 
contracts are check at runtime - so they stay current, which means the 
docs stay current (if they are generated from the contracts/code).
-Charlie

>
> "A rose by any other name ..."
>
> Regards,
>
> -- 
> -mark.  (probertm @ acm dot org)
>
>