Tim,

>From my point of view there are at least a few things that seem clear:

1. I think that Gregg Reynolds and I agree on a lot, but I would add to his 
remarks that there is almost always a human audience for source code, as 
well as the compiler/interpreter.  Sometimes, the audience is just the 
originally programmer, perhaps at a later date.  (If I missed something, 
Gregg, sorry, but I don't think you disagree, anyway.)

2. Since Clojure is a general-purpose tool, Clojure source code has no 
single kind of human audience for the code.  

In general, I do different things with comments, or with my coding style, 
depending on whether I expect that I will be the only maintainer of the 
code, or expect that others with whom I'm collaborating will need to 
interface with it, for example.  Further, I think about the skill levels 
and background of those who will read the code.  And I think about what 
they would want to do with it.  And then I make decisions that involve 
tradeoffs between competing desiderata.

3. There is a tradeoff between the desire to see a lot of code at once, 
without a lot of text cluttering it up, and understanding what the code is 
doing.  Comments hurt the former but can help the latter.  The same thing 
goes for literate programming, but--it depends on your goals and your human 
audience.

4. Two examples to convey the context-dependence of appropriate 
configuration schemes:

A. One time I wrote a small but slightly complex bit of code (in Perl, not 
Clojure).  I could see that it would be confusing, if someone just started 
reading the code at an arbitrary place.  But I also knew the ability of the 
other programmers I worked with, and I knew that if they started reading at 
one particular function, they would be able to figure out most of the 
rest.  I provided text that explained what they wouldn't be able to figure 
out.  About six months after I left the company, one of the programmers 
contacted me and asked me to explain the program; he had to make a 
modification.  I told him to look at such and such document, which mainly 
said "Start reading the code at such and such point, and understand these 
few other things."  He did, and that was all he needed.  If I wrote more 
documentation, I would only be duplicating the information that was already 
there in the source code, and that would be apparent for the kind of people 
who would read it.  In fact, if I provided *more* documentation, I doubt 
that the other programmers would have read it.  They would have just looked 
at the source.

B. Another example.

I generally don't like the idea of LP.  That is to say, I like the idea of 
people who want to be able to use it, using it, but I don't want to use it, 
usually.  And the reason that I don't want to use it is not simply that I 
don't want to bother writing it.  It's that I want the ability to use 
simple tools and I want to have relatively uncluttered source code.  (I 
could use LP and have uncluttered source much of the time, but only by 
using special tools.)

In my current main project, there is source code that implements the 
central functionality of the application, and there are rather complex 
configuration files.  I write documents to describe the central 
functionality source code, so that someone who wants to hack on it will 
know where to start and where to look.  I have to trust that they will know 
or will be willing to learn Clojure, because otherwise I'd have to explain 
too much.

However, the configuration files should be modifiable by people who won't 
understand the guts of the program, and yet, they are in Clojure, and would 
be pretty unintelligible to someone who merely understood in general what 
the program was supposed to do.  (I may create a DSL for the config files, 
but all that will do will be to get rid of a few parentheses.  The 
information in the config files won't be expressed significantly more 
succinctly.)

For the first time I'm thinking of using LP.  It would be perfect for the 
config files, and in fact, any other way of documenting the config files 
will probably be inadequate.  Interspersing explanations with the 
configuration code is precisely what's needed.

-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your 
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
--- 
You received this message because you are subscribed to the Google Groups 
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Reply via email to