Re: [Axiom-developer] Heidegger, literate programming, and communication

[Gregg Reynolds]

On Wed, May 21, 2014 at 4:39 PM, Mars0i <address@hidden> wrote:

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.)

I agree; whoever writes the code automatically forms an "audience" of one.  I guess I would say "reader/responder".

 

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.

Exactly.  Conclusion: it's hard, maybe impossible, to generalize about what all code should look like.  Maybe it's essentially pluralistic.

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.

Yep; there's always a point of diminishing returns.  I find that in developing code (or trying to understand others' code) I often take extensive notes and sometimes try to mentally "improve" what I deem sloppy or hard-to-read by writing a clear description of it, or just expressing it in different language.  But once I get comfortable with the code I don't often return to my documentation.

...

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.

I agree, that's a case where monolithic LP is entirely appropriate.  Ditto for APIs and unit tests; maybe also for simplified examples of API usage expressly designed for training.

-Gregg