[plt-scheme] Vision behind Scribble

Documentation, especially design/architecture and specification, should, 
imho, be finished before coding is started. For me comments are a means to 
clarify little details of code that may not immediately be clear to the 
reader/maintainer of the code. This does not imply that comments aren't 
important. They must not be formalized, I think. They are an informal means 
to clarify the formal parts. They also may, or rather they must, contain 
references to the design and specification. In the design stage I don't want 
my mind to be limited to a specific formalism, on the contrary, I want all 
my creativity to grow unbound. You may compare this to the way a 
mathematicien makes proofs ABOUT formal proofs. When talking ABOUT the 
formal system, all convincing arguments are allowed, informal ones included. 
We must be able to step out of the formal system in order to see what going 
on within that system.
Jos

----- Original Message ----- 
From: <hendrik at topoi.pooq.com>
To: <plt-scheme at list.cs.brown.edu>
Sent: Tuesday, March 18, 2008 7:25 PM
Subject: Re: [plt-scheme] Vision behind Scribble


> On Tue, Mar 18, 2008 at 12:54:11PM -0400, Doug Orleans wrote:
>> For me, the biggest reason to put the documentation in the source code
>> is to reduce the chance of them getting out of sync.  It's much easier
>> to update the documentation when it's right there next to the code
>> than if it's in some other file.  But maybe this could be done better
>> with the right tools-- maybe a hyperlink next to the code that brings
>> you to the appropriate doc file to edit.  Are there any systems
>> (e.g. Emacs packages) that work like this?
>
> Yes, documentation should be in the source code.  It's the only way to
> keep it in sync, and that only if the programmers go to the trouble of
> maintaining it.  It it's separated from the source code, it will get
> lost.
>
> But not all the documentation fits with the source code.  Perhaps the
> most prominent example is a system which consists of multipls source
> files.  The documentation that explains the large-scale structure or
> the purpose of the system or how the end-user should approach it does
> not belong in any of the pieces.
>
> No.  This isn't a solution.  The solutions we have solve only parts
> of the problem.  That doesn't mean they're useless.  It means that we
> have to recognise their limitations and do the extra ourselves.
>
> -- hendrik
> _________________________________________________
>  For list-related administrative tasks:
>  http://list.cs.brown.edu/mailman/listinfo/plt-scheme