[plt-scheme] Re: Scheme sources readability

From: Eli Barzilay (eli at barzilay.org)
Date: Sun Sep 7 23:35:36 EDT 2008

On Sep  7, kbohdan at mail.ru wrote:
> Matthias Felleisen wrote:
> >> After many years of programming i found new-old
> >> scheme world very fascinating. One thing i still
> >> do not like here is source code readability.
> > 
> > Code in Scheme tends to be 1/4 or 1/3 of the size of Java.
> > The indentation structure is far more revealing than there.
> > So I find it as readable as Java or better. You could argue
> > CL is better, I wouldn't respond then.
> Yes, agree code size is much smaller, but i'm still not sure if it
> helps me to read it.  Lets compare with Java: If i see class names
> like XxxAdapter, XxxVisitor, XxxFSM, XxxModel/XxxView/XxxController
> it only takes a seconds to understand what is going on.

* You'll need to know what "Adapter", "Visitor", "FSM", etc mean to
  get a clue about the purpose of the code.  At least "Visitor" is
  something that originates with a Java problem, so you'll need to
  know Java (culture) to really know what it means.

* Still, these are only names that hint at the intended behavior.  As
  such, you can do the same in any programming language (that doen't
  cripple its identifiers).

* For example in Scheme, you'll see things like `print-foo',
  `set-foo-length!', and `foo?' that take seconds to understand what
  is going on.  And like in Java you'll see names like `current-foo',
  `with-foo' and others that rely on (PLT) Scheme cultural idioms.
  Note also that there is nothing that prevents you from calling your
  modules/classes/functions names like `foo-model', `foo-view', etc,
  if you like to organize code in that particular way.

> Can you take any non-trivial snippet from DrScheme collects to
> demonstrate your algorithm of code reading?

Whatever "algorithm" people use to read code, there's no way to escape
learning the language.  In the case of PLT it includes a *lot* of
stuff that you need to know about, because there's plenty of
functionality that it has.  So choose any (small) piece of code that
looks interesting, or maybe looks similar to something that you want
to do, and start going over the source while reading about the
functionality that you find.  DrScheme will make it easier, by
providing you will tools like check-syntax.

> >> What about docstrings,
> > 
> > We consider Help Desk a priority because its linked way
> > of doing docs is superior. As my PhD advisor used to say,
> > a program (he meant module) is only worth writing if you
> > also write a paper about it (he meant documentation).
>    "Help Desk" helps me to understand public interface, but it
> doesn't help me too much to understand implementation.  From your
> point of view nobody guarantee that it should be easy for third
> person to understand even interface of private module not even
> saying about its implementation. IMHO, this is not the case for
> commercial software development.

Looks to me like you're confusing the role of doc strings: they're a
particular form of documentation that happens to be attached to the
function objects in a way that makes them interactively available.  If
anything, this means that they tend to be *shorter* than a manual
entry, and in any case, both forms of documentation should talk about
nothing more than the public interface.  The actual implementation can
change at any point, and comments are the tool for making such
maintenance jobs easier.

> >> design patterns (like GoF),
> > 
> > The design patterns of GOF were invented to address weaknesses in
> > Java and C++'s expressiveness when compared to Scheme and
> > LISP. Plus, when we discover a "pattern", we just turn it into a
> > construct via syntactic extensions.
> Design patterns (DP) were invented by architect not by programmers.

[This is an odd statement.]

> In programming DP are addressing history proven successful code
> patterns used both in coding and understanding source code.  Despite
> the fact that i can implement most of patterns as macros doesn't
> mean that scheme community should not pay attention on architecture
> and force all starting scheme programmers to invent the bike.

The fact that some design patterns can be implemented as macros mean
that they would frequently be implemented -- so why not focus on
things that you need and look into them instead of a vague "where are
The Scheme Patterns listed?" question?

On Sep  7, kbohdan at mail.ru wrote:
> Jens Axel Soegaard wrote:
> > One man's design pattern is another man's macro.
> Then what about "scheme specific design patterns" book gathering
> successful higher-order macro programming practice or at least ideas
> like:
>     - DSLs (ex: define-type, type-case from PLAI)

There's no real "pattern" here, besides the fact that you have macros
as a feature than can extend your language.  (And BTW, it is
questionable whether slapping one extra feature like
`define-type'/`type-case' gives you a DSL -- if you're familiar with
PLAI, then read about DSLs there.)

>     - monads
>     - coroutines
>     - pattern matching
>     - parser combinators

These are useful facilities in general.  In the context of PLT there
is no explicit support that I know of for coroutines -- because we
have threads and we have continuations (so make them be the relevant
"DP", for some definition of "DP").  Pattern matching is available
through `match' (see the manual for details).  Monads, IIRC, were
implemented in several different ways by several people.  Parser
combinators are not something that I'd consider a DP.

On Sep  7, kbohdan at mail.ru wrote:
> Definitely each of them is worse separate book, but the aim is to
> have catalogue of "common programming ideas" with
> sample-implementaion and sample usage.  IMHO, whole community can
> benefit from such catalogue-book.

Take `match' for example -- how will a sample implementation help?
What's missing in the current documentation for PLT's match?

On Sep  7, kbohdan at mail.ru wrote:
> Grant Rettke wrote:
> >>  Design patterns (DP) were invented by architect not by
> >>  programmers.
> > 
> > Architect == Senior Programmer
> "Christopher Alexander" == Senior Programmer ? :)

(I hope that this was a joke...)

          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
                  http://www.barzilay.org/                 Maze is Life!

Posted on the users mailing list.