[plt-scheme] Diagrams

We have no automatic support for diagrams other than the module browser 
and, in principle, the value flow graphs of the various soft typers 
(none applies to the current PLT languages).

Personally I believe that if a diagram is generated from code then 
you're better off generating it on demand. So I stay away from them. 
That said, however, I use class diagrams on occasion to communicate the 
essence of my code to my students in Software Dev when I do code walks. 
Yes, that means I am doing it backwards. Like Noel, I find an algebraic 
datatype definition `a la ML more informative than a UML diagram.

When I have to document my own software, I do it in two ways:

  1. for external user documentation, I make it a habit of editing
     the program and documentation file simultaneously. They are
     always in sync (unless I mess up). The external documentation
     is almost always an English transliteration of the module
     interface plus examples.

  2. for internal documentation, I use contracts and purpose
     statements in the spirit of HtDP plus additional comments
     when I find a function too complex. To make sure this works,
     I try to break up functions and class definitions into
     pieces that are documentable. Often this means 1 screen on
     my Robby-ordered 24in Mac display.

-- Matthias

On Jan 14, 2006, at 8:57 PM, Richard Cleis wrote:

> Do guidelines exist for diagramming scheme-like languages?  We have 
> written fairly extensive scheme programs for automating laboratory 
> equipment, and now I need to document the work.
>
> rac
>
>
> "All truth passes through three stages. First, it is ridiculed. 
> Second, it is violently opposed. Third, it is accepted as being 
> self-evident." - Arthur Schopenhauer 
> _________________________________________________
>   For list-related administrative tasks:
>   http://list.cs.brown.edu/mailman/listinfo/plt-scheme