Heidegger, literate programming, and communication

[d***@axiom-developer.org]

The primary focus of a "documentation system" is communication from
the author to the audience.

One of the struggles apparent in discussing issues of communication,
especially with programmers, is Heideggers "present-at-hand" vs
"breaking down".

Programmers write programs to instruct a machine to perform some
task. In the ideal, this involves "communication" from the mind of
the programmer to the "execution of the program". If the program works
the first time it is all a seamless entity ("present-at-hand").

When the program fails, by compiler errors, missing libraries, runtime
errors, design errors, inappropriate actions, or any of the other dragons
of programming, the process is not seamless. The details of the process
rise to our awareness ("breaking down"). The burden of failure is likely
to fall on people who use or maintain the program rather than the authors.
If the program survives, these are likely audiences.



Programmers, generalizing from my own case, rarely have a seamless
experience. Programs that work the first time, are correct, efficient,
and all of the other properties, are rather far outside our experience.

The effect of this constant "breaking down" is that we have learned,
rather painfully, to be aware of the machinery of the process at every
step of the way. This focus on the machinery becomes the expected way
of communicating with the machine. Scratch any programmer, interview at
any company, listen to any talk, and you find "machinery".

But communication from the author to the audience is the underlying
theme of literate programming. Knuth's point is about communication,
not about the machinery of communication. The question is, to what
audience, not how.



Discussions seem to get lost in a debate about the machinery rather
than the goal. We focus our debate on docstrings versus markup versus
wiki. We consider literate programming to be "too much machinery".

In these forums there is rarely find any example of "present-at-hand"
issues of communication. That is, given a large program (e.g. Axiom,
Clojure), what is it that we need to communicate, to what audience,
and at what level of detail?

Axiom focuses on "The 30 year horizon" under the assumption that the
computational mathematics will be forever valid and that the audience
will be unable to contact the likely-dead authors.

Pharr and Humphreys' "Physically Base Rendering" [0] is written as a
literate program, a book that won an Academy Award, using Tex and
C++. The very first thing they mention in the preface is the
"Audience". They communicate to humans and, also, to machines.

What is the audience for Clojure?

Common Lisp has achieved a long-term horizon by raising the language
to a standard. No standard is perfect but it does make it possible to
construct programs which have a stable base for communication. That
base makes it possible to write a book like "Lisp in Small Pieces" [1]
which communicates ideas in natural language using an embedded program
as a reduction to practice.



So the fundamental point is what to communicate to what audience,
not how to implement it. Different audiences will need different
implementations (e.g. docstrings for REPL users) but we must avoid
losing ourselves in the noise.

Axiom, by choice, has a defined audience. Does Clojure?

Tim Daly
***@axiom-developer.org

[0] Pharr, Matt; Humphreys, Greg
Physically Based Rendering
ISBN 978-0-12-375079-2
[1] Queinnec, Christian
Lisp in Small Pieces
ISBN 978-0521545662

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Gregg Reynolds]

Hi Tim,

I'm glad you're continuing the conversation, which has helped me at least
to clarify my thinking about not just LP but about the nature of
programming and the sort of tools we (or I at least) need to support good
programming. I end up in a very different place than you, but I don't
think it's a zero-sum game. Please take the comments below in the irenic
spirit in which they are offered - not "you are wrong on so many levels
that I'm compelled to enlighten you", but "here are some other ways to look
at things that seem interesting."

On Wed, May 21, 2014 at 6:03 AM, <***@axiom-developer.org> wrote:

> The primary focus of a "documentation system" is communication from
> the author to the audience.
>

Communication is an important part of the puzzle, I agree; but what exactly
is it? There are lots of
models<http://en.wikipedia.org/wiki/Models_of_communication>,
which carry very different implications.


>
> One of the struggles apparent in discussing issues of communication,
> especially with programmers, is Heideggers "present-at-hand" vs
> "breaking down".
>
> Programmers write programs to instruct a machine to perform some
> task. In the ideal, this involves "communication" from the mind of
> the programmer to the "execution of the program".


This suggests a transference or transmission model of communication based
on what Roy Harris <http://www.royharrisonline.com/INP26.html> calls the
"telementation" and fixed-code fallacies - the idea that communication
involves transference of some kind of content ("thoughts", "concepts",
etc.) from one mind to another, or to a machine, by encoding, sending,
receiving, and decoding "messages". That may be a good model for
computational communication, but it has severe (and I think insurmountable)
problems as a model for human communication. More fundamentally, whether
human-computer interaction should be considered communication at all is
problematic to say the least.

For a terrific study on communication check out Michael Tomasello's Origins
of Human Communication<http://books.google.com/books/about/Origins_of_Human_Communication.html?id=T3bqzIe3mAEC>.
The suggestion there is that successful communication amounts to successful
coordination of joint action.

The notion that programs "instruct" a machine to perform some task is very
common - it's arguably central to Knuth's concept of LP - but I'm not
convinced it is correct. In a sense, a program just *is* a machine, albeit
an abstract one. When you compile it, you just translate it into another
language, yielding an equivalent machine, one that a physical machine
"understands". When you "run" the machine program, it doesn't "instruct"
the hardware to do this or that, any more than the laws of physics
"instruct" apples to fall in a certain way, or a hurled stone "instructs"
the window it meets to shatter.

...snip...

The effect of this constant "breaking down" is that we have learned,
> rather painfully, to be aware of the machinery of the process at every
> step of the way. This focus on the machinery becomes the expected way
> of communicating with the machine. Scratch any programmer, interview at
> any company, listen to any talk, and you find "machinery".
>

How could it be otherwise? Programming is machine construction.

>
> But communication from the author to the audience is the underlying
> theme of literate programming. Knuth's point is about communication,
> not about the machinery of communication. The question is, to what
> audience, not how.
>

I'm not sure what "machinery of communication" means. It's not something I
ever think about when I'm programming; in fact I never think about
communication. I think about language, logic, and expressiveness. Whether
others understand what I write is not something I can control; all I can do
is try to write clearly under the constraints of the language I'm using.
The problem with focusing on communication is that successful communication
is the responsibility of all parties involved. Authors can be held
responsible for what they write, but not for what readers read; this is
true for all forms of writing. There's not much an author can do to
prevent readers from misreading, other than try to write clearly.
Unfortunately, the Principle of
Charity<http://en.wikipedia.org/wiki/Principle_of_charity>is routinely
ignored (especially on the internet!)

Knuth: "Instead of imagining that our main task is to instruct a
*computer*what to do, let us concentrate rather on explaining to
*human
beings* what we want a computer to do." Notice how Knuth changes horses in
midstream, from "instructing a computer" (i.e. writing code) to "explaining
to humans", which is not writing code. The conclusion that many (well,
some) have drawn is that we should treat the "literary explanation" as
central, and the code as secondary or even incidental. I guess that's ok
if your task is to explain a program, but as a model of what programming is
or ought to be, it's not even wrong. The *only* reason to write a (real,
not toy or pedagogical) program is so that a (physical) machine can run
it. If it can't be run, or if it produces the wrong result, then it
doesn't matter how good the documentation is.

Here's the Knuth quote from his LP article nobody ever cites: ""In fact,
my enthusiasm is so great that I must warn the reader to discount much of
what I shall say as the ravings of a fanatic who thinks he has just seen a
great light." We should take him seriously.

[Also, as a historical matter, Knuth himself clearly had strong ideas about
the "how" involving things like "natural" narrative order, monolithic
text+code, etc.; see the quotes at
https://github.com/mobileink/codegenres/wiki/Quotations.]

The notion that programmers should focus on documentation addressed to
humans is where I part company with Knuth (and just about everybody else, I
reckon). Time spent writing "magnificent" documentation is time that could
be spent making the code better and more understandable. I actually think
that Knuth completely misunderstood the nature of programming. I do *not*
think that programming **essentially** involves "communication" with other
humans (although it arguably does involve coordination with other humans).
Or with machines, for that matter. The essence of programming is the
construction of machines, which is something that creatures lacking natural
language can do in principle and do in fact do - there are many examples of
non-human animals constructing and/or using machines (e.g. primates using
sticks to pull termites out of a mound). When you compile and run a
program there is no communication of ideas going on - machines obviously do
not have ideas. What's really happening is that you arrange the physical
world in such a way that it behaves the way you want it to behave. (Let's
not forget that program text is physical - a configuration of "bits" in a
piece of hardware - which we construct using our fingers at a keyboard;
also, that there is no distinction to be made between (formal) language and
machine.)

The fact that we draw on natural language to define the symbols of our
programming languages (the sprockets of our machines) is entirely parasitic
on the primitive notion of machine (formal language). We could replace all
the keywords of our favorite language by random strings, and programming
would still be possible in principle; that's trivially obvious, but it is
not trivial. It means that human communication is not a primitive element
of programs.

Yet for obvious practical reasons we do prefer to use natural-language
facsimiles in our programming languages - facsimiles, since predefined
formal strings like "map" or "conj" only look like natural language words.
And when we define local names we invariably use natural-language-like
terms. The possibility of doing this is obviously very useful, but it
remains secondary to the primitive structure of mindless symbol
manipulation machinery. Choosing a good natural-language representation
for a variable or function name involves finding a word or phrase that
*expresses* the computational semantics, and *that* is where human
communication enters the picture: the expressiveness of the programming
code itself, as a hybrid of quasi-natural-language piggybacking on abstract
formal language.

This suggests an alternative to LP "methodology": programming not as
literary composition but as language design. Program texts to be viewed
not as essays expressed in a programming language, but as extensions of the
language. For example, every function definition of arity > 0 effectively
defines a mini-DSL as an extension of the base language. The parameters to
the function are "terms" that are locally (temporarily) added to the
lexicon. Ditto for "def"ed names. Lambda expressions ("anonymous"
functions) are themselves names - you can view them as one-off names, or
you can think of the language lexicon as already implicitly containing all
possible lambda expressions as names. If your language has hygienic macros
like Clojure you can extend the syntax as well. A "good" language
extension (program) is one that uses the expressive resources of a natural
language to extend the vocabulary and/or syntax of the base language in
"good" ways - good involving principles of clarity, parsimony, etc. On
this view documentation is entirely external to programming.

In any case, the result is a radically different view of what programming
is all about: programmers not as mere users of languages designed by
others, but as designers of (derived) languages, whose task is to extend
programming languages in ways that fit (express) the problem domain. Every
program is then viewed as a kind of DSL design. Libraries are DSLs that
can be used in other designs. Locals are not "variables", which puts the
focus on semantics, but "lexical extensions", which puts the focus on
language and thus expressiveness. Etc. Since programming language
designers are generally held to a higher standard with respect to clarity
and expressiveness - you'd better put some serious thought into syntax and
predefined names if you're going to design a new language - programmers who
think of themselves as language designers might do a better job of writing
understandable programs.

And from this perspective documentation is a completely separate issue
that should not be confused with writing code. (I am NOT saying that
documentation is unimportant, only that it is not to be conflated with
programming.)

So I would modify Knuth's plea to something like ""Instead of imagining
that our main task is to instruct a *computer* what to do, or to
explain to *human
beings* what we want a computer to do, let us concentrate rather on
designing *expressive* languages that solve our problems." Needs work I
guess, but you get the idea. Improve programming. Also improve
documentation. Don't confuse the two.


> Discussions seem to get lost in a debate about the machinery rather
> than the goal. We focus our debate on docstrings versus markup versus
> wiki. We consider literate programming to be "too much machinery".
>

Not too much, but the wrong kind of machinery.

>
> In these forums there is rarely find any example of "present-at-hand"
> issues of communication. That is, given a large program (e.g. Axiom,
> Clojure), what is it that we need to communicate, to what audience,
> and at what level of detail?
>

Or, for what purpose? The author cannot determine who reads his or her
work, but can decide on a purpose. You might write a book with a college
freshman audience in mind, but to me that translates into "for the purpose
of instructing people with a certain level of knowledge and experience",
which frees it from any particular social group.

Even though I've challenged some of your assumptions I think you are right
to stress this aspect of program texts and documentation - the purpose (or
intended audience, or whatever we want to call it). Lots of comments on
behalf of LP ignore this; a common ploy is to offer an expressly
pedagogical LP text as an example that generalizes to programming of all
kinds. But different purposes (audiences) demand different approaches.
(I've sketched out some ideas along these lines at
https://github.com/mobileink/codegenres/wiki/Code-Lit.) The presentational
output of LP is great for some purposes, so LP may be a good method; but
note that that does not imply that the source from which such a
presentational form is generated must be an LP text.


>
> Axiom focuses on "The 30 year horizon" under the assumption that the
> computational mathematics will be forever valid and that the audience
> will be unable to contact the likely-dead authors.
>
> Pharr and Humphreys' "Physically Base Rendering" [0] is written as a
> literate program, a book that won an Academy Award, using Tex and
> C++. The very first thing they mention in the preface is the
> "Audience". They communicate to humans and, also, to machines.
>

The goal of the book is explicitly pedagogical, so LP is useful. But it
doesn't generalize to all purposes.

PBR is clearly becoming the poster child for LP. It won an award! LP
good! (I'm not saying that's what you mean here. I'm just sayin'.) But
what won the award was the book - the explanation, presentation, and
content of the book/program, not the LP source text of the book/program.
The award was for "for their formalization and reference implementation of
the concepts behind physically based
rendering<http://www.oscars.org/press/pressreleases/2014/20140108.html>"
- not for using LP. In principle the same book could have been produced by
other methods.

>
> What is the audience for Clojure?
>

I don't think it has an "audience" - it's a tool, not a text. But it does
have markets - programmers and other users of such tools.

>
> Common Lisp has achieved a long-term horizon by raising the language
> to a standard. No standard is perfect but it does make it possible to
> construct programs which have a stable base for communication. That
> base makes it possible to write a book like "Lisp in Small Pieces" [1]
> which communicates ideas in natural language using an embedded program
> as a reduction to practice.
>

A great book, but it's not really about CL in particular. It's mostly
Scheme, and it's not LP. So I'm not sure why you're citing it - is your
point that it exemplifies narrative prose with embedded code? Maybe I'm
not following your point about communication here.


> So the fundamental point is what to communicate to what audience,
> not how to implement it. Different audiences will need different
> implementations (e.g. docstrings for REPL users) but we must avoid
> losing ourselves in the noise.
>

You can say that again. Another major source of noise is failure to
distinguish between the presentational output of classic LP and the use of
LP tools and techniques. There's more than one way to get that sort of
output.


>
> Axiom, by choice, has a defined audience. Does Clojure?
>

I'm not sure what you're getting at with this question. What kind of
answer would count as a good one, for you?

Cheers,

Gregg

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Mars0i]

On Wednesday, May 21, 2014 6:03:04 AM UTC-5, ***@axiom-developer.org
wrote:
>
> The primary focus of a "documentation system" is communication from
> the author to the audience.
>
> One of the struggles apparent in discussing issues of communication,
> especially with programmers, is Heideggers "present-at-hand" vs
> "breaking down".
>
> Programmers write programs to instruct a machine to perform some
> task. In the ideal, this involves "communication" from the mind of
> the programmer to the "execution of the program". If the program works
> the first time it is all a seamless entity ("present-at-hand").
>
> When the program fails, by compiler errors, missing libraries, runtime
> errors, design errors, inappropriate actions, or any of the other dragons
> of programming, the process is not seamless. The details of the process
> rise to our awareness ("breaking down"). The burden of failure is likely
> to fall on people who use or maintain the program rather than the authors.
> If the program survives, these are likely audiences.
>
>
>
> Programmers, generalizing from my own case, rarely have a seamless
> experience. Programs that work the first time, are correct, efficient,
> and all of the other properties, are rather far outside our experience.
>
> The effect of this constant "breaking down" is that we have learned,
> rather painfully, to be aware of the machinery of the process at every
> step of the way. This focus on the machinery becomes the expected way
> of communicating with the machine. Scratch any programmer, interview at
> any company, listen to any talk, and you find "machinery".
>
> But communication from the author to the audience is the underlying
> theme of literate programming. Knuth's point is about communication,
> not about the machinery of communication. The question is, to what
> audience, not how.
>
>
>
> Discussions seem to get lost in a debate about the machinery rather
> than the goal. We focus our debate on docstrings versus markup versus
> wiki. We consider literate programming to be "too much machinery".
>
> In these forums there is rarely find any example of "present-at-hand"
> issues of communication. That is, given a large program (e.g. Axiom,
> Clojure), what is it that we need to communicate, to what audience,
> and at what level of detail?
>
> Axiom focuses on "The 30 year horizon" under the assumption that the
> computational mathematics will be forever valid and that the audience
> will be unable to contact the likely-dead authors.
>
> Pharr and Humphreys' "Physically Base Rendering" [0] is written as a
> literate program, a book that won an Academy Award, using Tex and
> C++. The very first thing they mention in the preface is the
> "Audience". They communicate to humans and, also, to machines.
>
> What is the audience for Clojure?
>
> Common Lisp has achieved a long-term horizon by raising the language
> to a standard. No standard is perfect but it does make it possible to
> construct programs which have a stable base for communication. That
> base makes it possible to write a book like "Lisp in Small Pieces" [1]
> which communicates ideas in natural language using an embedded program
> as a reduction to practice.
>
>
>
> So the fundamental point is what to communicate to what audience,
> not how to implement it. Different audiences will need different
> implementations (e.g. docstrings for REPL users) but we must avoid
> losing ourselves in the noise.
>
> Axiom, by choice, has a defined audience. Does Clojure?
>
> Tim Daly
> ***@axiom-developer.org <javascript:>
>
> [0] Pharr, Matt; Humphreys, Greg
> Physically Based Rendering
> ISBN 978-0-12-375079-2
> [1] Queinnec, Christian
> Lisp in Small Pieces
> ISBN 978-0521545662
>

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Mars0i]

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 ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Gregg Reynolds]

On Wed, May 21, 2014 at 4:39 PM, Mars0i <***@logical.net> 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

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[u1204]

Gregg and Gary,

I understand where you are coming from. Indeed, Maturana [0] is on your
side of the debate. Since even the philosophers can't agree, I doubt we
will find a common ground.

Unfortunately, I've decided to take on the task of documenting the
Clojure internals because, yaknow, *I* don't feel I understand something
until I know what the hardware does; consider this a flaw in my
personality :-) I have to say that the posted Clojure code is
"somewhat lacking" in the communication department. Perhaps it is only
intended for an "audience of one", and I'm not "the one". :-)

Contrary to popular belief, I am reading the code. As a result, I have a
strongly held opinion that there is a lot that could be done to make
it less of a struggle.




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

Hmmm. Common Lisp is about 25 years old. Assume Clojure lives that long.
What are the odds that the original authors will be maintaining the
code? Will the code still be "an audience of one"? Are you sure that's
a worthwhile goal?



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

My experience "in industry" with "general-purpose tool" code is that
code does look a lot different from project to project and language to
language. But as code moved out of its childhood and off the desk, it
began to grow hair and get ugly. The authors all assumed they would be
"the only maintainer". For instance,

I once had to maintain a C program that had 14 pages of nested ifdefs
just to choose the correct #include files. Each include file had
ifdefs. The code ran everywhere, Intel, ARM, 68000s, SUNs, DEC,
etc. but nearly every line was based on experience (e.g. compensating
for floating-point errors on various platforms, hacking around errors
in various C compilers and their "optimizers", etc.) with ifdefs
around each hack. I had to run the compiler intermediate stage to
figure out what the actual code would be for my platform. And then I
had to reverse-engineer the fix into the appropriate include files;
uncommented I might add. I wouldn't want to ruin the style.

Sophisticated Lisp programmers use macros A LOT. Axiom, for instance,
compiles code from a high-level algebra language, essentially a DSL,
into macros that index into vectors for the function to call, or the
category to inherit which might contain the call, and the environment
passed to each function is a huge vector. DSLs, which make the top
level code "so clear", often are macros generating machine-code-like
lisp doing super-efficient vector indexing. One finds macros
expanding into macros expanding into macros. Quick, what does the
spadcall macro do?

And we won't even mention that despite the use of a DSL, the DSL
code isn't "perfectly clear" either. This is especially true when
it gets mixed with inline, non-DSL code. For instance, Axiom's
algebra code regularly invokes low-level lisp functions.



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

Yes, it is hard to generalize about what all code should look like. But
it is not hard to generalize that reading natural language explanations
is faster, more accurate, and a lot easier than reverse-engineering
code. It is MUCH easier to understand Greg Humphrey's rendering code
than it is to understand the Clojure internals.

Consider a randomly chosen paragraph from Physically Based Rendering
(p356):



To do the permutation, this function loops over the samples, randomly
permuting the sample points in one dimension at a time. Note that this
is a different permutation than the earlier Shuffle() routine: that
routine does one permutation, keeping all nDim sample points in each
sample together, while here nDim separate permutations of a single
dimension at a time are done. (Figure 7.21)

for (uint32_t i = 0; i < nDim; ++1) {
for (uint32_t j = 0; j < nSamples; ++j) {
uint32_t other = j + (rng.RandomUInt() % (nSamples - j));
swap(samples[nDim + j + i], samples[nDim * other + i]);
}
}

Footnote: While it's not necessary to permute the first dimension of
the LHS pattern, the implementation here does so anyway since making
the elements of the first dimension be randomly ordered means that LHS
patterns can be used in conjunction with sampling patterns from other
sources without danger of correlation between their sample points.



So we learned what the code does. We also learned not to "optimize the
code" by replacing it with Shuffle(). Further, we learned that we
shouldn't "optimize the code" by removing the apparently useless
shuffle of the first dimension. And, as a bonus, we get a figure.
NONE OF THIS INFORMATION IS IN THE CODE ITSELF.

In addition, this code lives in an organizing structure. It is
in Chapter 7: Sampling and Reconstruction
Section 7.3: Stratified Samples


Heck, it is only 4 lines of C++. Why bother? *I* can read C++. I can
even reverse engineer it (probably by inventing the diagram in Figure
2.7 on a napkin). Maybe it lives in the src/SamRecon/StratSam, which is
all the organization necessary. :-) But I can't reverse engineer the
important information in either paragraph of text.

For comparison, refer back to the multi-page Java code I posted
from the Clojure core. As a maintenance programmer, which would you
rather maintain?




Estimates are that programs that "live" spend 80% or more of their
"lifetime" in maintenance.

Companies that depend on a "crufty old program" (a l33t-speak term for
any program not authored by the current maintainer) are willing to pay
the cost to have programmers read the code, take notes, and spend time
reverse-engineering the code.

In contrast, open source code tends to die the moment the original
authors stop typing. Sourceforge, github, savannah, etc. are
wall-to-wall full of code nobody will ever use. It is very common to
see someone write:

"Well, it hasn't been updated in the last 6 months so I don't think
it is being maintained anymore."

Being an "audience of one" when writing the code means the program
will have an "audience of one" in github; until 6 months pass and it has
an "audience of zero".

Languages come into fashion all the time. Almost all of them disappear.
Axiom and Clojure are worthwhile efforts. We really need a mindset that
extends into the future, communicating with the maintainers.

Tim Daly


For want of a comment, the fix was lost.
For want of a fix, the routine was lost.
For want of a routine, a program was lost.
For want of a program, the customer was lost.
For want of a customer, the company was lost.

[0] Zeleny, M. (ed.)
"Autopoiesis, a Theory of the Living Organization"
New York, Elsevier-North Holland (1978)

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Gregg Reynolds]

Howdy Tim,


On Thu, May 22, 2014 at 1:16 AM, u1204 <***@axiom-developer.org> wrote:

> Gregg and Gary,
>
> I understand where you are coming from. Indeed, Maturana [0] is on your
> side of the debate. Since even the philosophers can't agree, I doubt we
> will find a common ground.
>

Ah, but philosophers never agree. Disagreement is part of their job
description. Why should programmers be any different?


>
> Unfortunately, I've decided to take on the task of documenting the
> Clojure internals because, yaknow, *I* don't feel I understand something
> until I know what the hardware does; consider this a flaw in my
> personality :-)


I suffer from a similar malady, which compels me to continually rewrite
other peoples code, since, gee whiz, "foo" is not quite the perfect name
for that darn variable, "bar" would be just slightly better, and on and
on. You can see why I prefer code to commentary.
...
>>
>> 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".

Hmmm. Common Lisp is about 25 years old. Assume Clojure lives that long.
> What are the odds that the original authors will be maintaining the
> code? Will the code still be "an audience of one"? Are you sure that's
> a worthwhile goal?
>

I think you may have misunderstood me (dunno about Gary): my point is that
even one-off code that gets discarded immediately has a human reader,
namely the author. A statement of (minimal) fact, not a goal.

...

>
> Sophisticated Lisp programmers use macros A LOT.


That's because they are language designers, and they know it.


> expanding into macros expanding into macros. Quick, what does the
> spadcall macro do?
>

HCF?

>Exactly. Conclusion: it's hard, maybe impossible, to generalize about what
> >all code should look like. Maybe it's essentially pluralistic.
>
> Yes, it is hard to generalize about what all code should look like. But
> it is not hard to generalize that reading natural language explanations
> is faster, more accurate, and a lot easier than reverse-engineering
> code.


Whoa Nelly! I don't agree with that at all, either in principle or by
experience. Well, ok, you've rigged the game. Easier than
"reverse-engineering code" - what does that mean? I guess you mean reading
well-written natural language explanations is faster etc. than reading
badly written code - but so what? It's not a meaningful comparison. Would
you take a comparison between a sample of well-written code and a sample
badly written LP as evidence against LP? I would not. To me the question
is whether well-written natural language explanation adds anything of
substance to well-written code.


> It is MUCH easier to understand Greg Humphrey's rendering code
> than it is to understand the Clojure internals.
>

Ok, but I don't see how exhibiting a piece of transparent code next to a
piece of opaque code demonstrates anything.


>
> Consider a randomly chosen paragraph from Physically Based Rendering
> (p356):
>
> To do the permutation, this function loops over the samples, randomly
> permuting the sample points in one dimension at a time. Note that this
> is a different permutation than the earlier Shuffle() routine: that
> routine does one permutation, keeping all nDim sample points in each
> sample together, while here nDim separate permutations of a single
> dimension at a time are done. (Figure 7.21)
>
> for (uint32_t i = 0; i < nDim; ++1) {
> for (uint32_t j = 0; j < nSamples; ++j) {
> uint32_t other = j + (rng.RandomUInt() % (nSamples - j));
> swap(samples[nDim + j + i], samples[nDim * other + i]);
> }
> }
>
> Footnote: While it's not necessary to permute the first dimension of
> the LHS pattern, the implementation here does so anyway since making
> the elements of the first dimension be randomly ordered means that LHS
> patterns can be used in conjunction with sampling patterns from other
> sources without danger of correlation between their sample points.
>
> So we learned what the code does. We also learned not to "optimize the
> code" by replacing it with Shuffle(). Further, we learned that we
> shouldn't "optimize the code" by removing the apparently useless
> shuffle of the first dimension. And, as a bonus, we get a figure.
> NONE OF THIS INFORMATION IS IN THE CODE ITSELF.
>

For "what the code does":

/* inline random, total, in-place matrix permutation - contrast Shuffle() */
...code...

The first line of commentary is totally redundant, so it is a waste of time
to read both it and the code. As for what not to "optimize": if none of
the conclusions you draw are in the code, they're not in the commentary,
either. Replacing the code with Shuffle would change the meaning from
total to partial permutation, so it would not be an optimization. Ditto
for replacing it with Shuffle. But the explanation of the difference
between this code and Shuffle is unhelpful to me - what does "[the Shuffle]
routine does one permutation, keeping all nDim sample points in each sample
together" mean? I'd have to read that code to find out, so the commentary
has just wasted my time. As for the permutation of the first dimension,
here the commentary is bad again - first it says it is not necessary, then
it explains that it is necessary if you want to use it for a specific
purpose. As for the figure, I assume the book has some kind of graphic. I
don't think I need a graphic to understand the code - it's a simple
permutation.

So for me at least, this example counts against rather than for the point
that (I assume) you want to make. The point I will make is not that
documentation is inherently evil - far from it - but merely that
explanatory prose is not a *necesssary* condition of readable code. And it
often makes things worse, as in this case.


>
> In addition, this code lives in an organizing structure. It is
> in Chapter 7: Sampling and Reconstruction
> Section 7.3: Stratified Samples
>
>
> Heck, it is only 4 lines of C++. Why bother? *I* can read C++. I can
> even reverse engineer it (probably by inventing the diagram in Figure
> 2.7 on a napkin). Maybe it lives in the src/SamRecon/StratSam, which is
> all the organization necessary. :-) But I can't reverse engineer the
> important information in either paragraph of text.
>
> For comparison, refer back to the multi-page Java code I posted
> from the Clojure core. As a maintenance programmer, which would you
> rather maintain?
>

Really? What's the point of comparing 4 lines of C++ and multiple pages of
Java? I can tell you I would rather maintain the four lines of C++ without
the largely useless commentary. I would also rather maintain a
(well-written) plain Pascal version of "Printing the primes" than the LP
version Knuth uses in his paper on LP (a web search will turn up a preprint
copy).

... snip ...

Languages come into fashion all the time. Almost all of them disappear.
> Axiom and Clojure are worthwhile efforts. We really need a mindset that
> extends into the future, communicating with the maintainers.
>

Dunno anything about Axiom, I'm afraid. As for the future, I think it is
best served by doing our best to write clear *code* now. You mentioned
Axiom has a 30 year timeline. I won't be surprised if humans do relatively
little hands-on coding (or code reading) by then. Between AI and automated
reasoning (for which the commentary part of LP is irrelevant) I expect the
number of programmer jobs to shrink drastically by then.

In any case, I wish you luck with your Clojure internals project. If XML
doesn't give you the hives check out
https://github.com/mobileink/xsl.clj-ext - I think it could be used to good
effect to document the APIs, if not the internals, by example.

-Gregg

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Andy Fingerhut]

On Wed, May 21, 2014 at 11:16 PM, u1204 <***@axiom-developer.org> wrote:

> Heck, it is only 4 lines of C++. Why bother? *I* can read C++. I can
> even reverse engineer it (probably by inventing the diagram in Figure
> 2.7 on a napkin). Maybe it lives in the src/SamRecon/StratSam, which is
> all the organization necessary. :-) But I can't reverse engineer the
> important information in either paragraph of text.
>
> For comparison, refer back to the multi-page Java code I posted
> from the Clojure core. As a maintenance programmer, which would you
> rather maintain?
>

Tim, as someone already mentioned, the multi-page Java code you posted from
"the Clojure core" is actually one file from the Java ASM library, copied
into the Clojure Github repository from one version of that library
available from here:

http://asm.ow2.org

There are 18,821 lines of Java code in that library, as it has been copied
into Clojure in the src/jvm/clojure/asm directory. I would strongly
recommend that you *not* spend a lot of time reading and documenting that
code, if you want to document things that are unique to Clojure. That
library is used by other projects besides Clojure. Between Clojure 1.5.1
and Clojure 1.6.0, a new version of it was copied over the older version
that was used before then.

http://dev.clojure.org/jira/browse/CLJ-713

That will likely happen again in a future Clojure release, to better
support JDK8:

http://dev.clojure.org/jira/browse/CLJ-1323

I would strongly recommend focusing on the 36,501 lines of Java code in
src/jvm/clojure/lang, and/or the 19,207 lines of Clojure code in
src/clj/clojure, first, and save the ASM library for later, if ever.

Andy

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Tim Daly]

>Tim, as someone already mentioned, the multi-page Java code you posted from
>"the Clojure core" is actually one file from the Java ASM library, copied
>into the Clojure Github repository from one version of that library
>available from here:

Hmmm, I didn't see that in the documentation :-)
Thanks for the warning.

In order to write the book I took a clone of the repository at a
particular time with the intention of "walking up the diffs" after
I had a clue about the details.

>There are 18,821 lines of Java code in that library, as it has been copied
>into Clojure in the src/jvm/clojure/asm directory.

Oh, good. That means I can read the library documentation :-)

> I would strongly
>recommend that you *not* spend a lot of time reading and documenting that
>code, if you want to document things that are unique to Clojure. That
>library is used by other projects besides Clojure. Between Clojure 1.5.1
>and Clojure 1.6.0, a new version of it was copied over the older version
>that was used before then.
>
> http://dev.clojure.org/jira/browse/CLJ-713
>
>That will likely happen again in a future Clojure release, to better
>support JDK8:

and again for JDK9... and again for JDK10... and again for...

If Clojure needs the library then it needs to be documented. I am
using a "reference" model. If code references a function then document
the function. If no code references the library then it won't get
documented.

Any living piece of software is going to have changes made but I'm
hoping that the core remain reasonably stable. Assuming, of course, I
can distinguish core code. Reading code is SO much fun :-)

Anyway, thanks for the warning.

Tim Daly


--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Andy Fingerhut]

On Thu, May 22, 2014 at 11:05 AM, Tim Daly <***@axiom-developer.org> wrote:

> >Tim, as someone already mentioned, the multi-page Java code you posted
> from
> >"the Clojure core" is actually one file from the Java ASM library, copied
> >into the Clojure Github repository from one version of that library
> >available from here:
>
> Hmmm, I didn't see that in the documentation :-)
> Thanks for the warning.
>

I know Clojure doesn't have all the documentation many would like, but Tim,
this bit of info is in readme.txt, and the first 3 lines of every source
file from the library :-)

Andy

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Tim Daly]

Forward from Ralf Hemmecke:


On 05/22/2014 11:21 AM, Gregg Reynolds wrote:
> I can tell you I would rather maintain the four lines of C++ without
> the largely useless commentary.

That's a simple AXIOM program, but I'm sure one can easily translate it
into any programming language.

foo(a: Integer, b: Integer): Integer ==
if a > 0 then
if a > b then return foo(b,a)
return foo(b-a,a))
return b

Question: Does the program have a bug?

Ralf

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Mars0i]

Tim,

Your project of LP'ing the Clojure internals is not at all inconsistent
with my view. That is code that would benefit from being widely
understood, even by people who won't maintain it. I learned a lot from
reading the "Lions" book on an early version of Unix, even though I
probably never even used hardware old enough to run it. (On the other
hand, I'm not sure that there should be documentation that explains the
complexities of the chunking mechanism both at the definitions of `map` and
`doseq`, for example. That seems redundant. Maybe LP software has
convenient ways of dealing with that sort of issue, though.)

And I agree that won't can't know what code will live for 25 years, and
what won't, and how many people will have to maintain the code. So one
approach is simply to assume that all code will live a long time and be
maintained by many people, many of whom will be unfamiliar with the code.
But that means that you waste a lot of time on code that gets put aside
(for reasons other than lack of documentation).

Yeah, there are tradeoffs. We have to make our best judgments.

One option: Write with whatever documentation you think will help the
code's forseen uses. Then, if you discover later, that it needs better
documentation, write it then. That won't be as easy as writing it in the
first place: In hindsight, it's less efficient, but it may be more
efficient overall across all projects. (i.e. one "faults in" the
documentation: It's sometimes most efficient to allocate all of an
executable's image and heap as soon it runs, but modern OSes instead often
allocate memory only as needed, which, in hindsight, is less efficient, but
overall, makes for a more efficient system.)

(I think I am the "Gary" mentioned above, although that isn't my name. But
I'm happy to take on that name in this discussion.)

-Gary

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Tim Daly]

>PS I have many chunks of code that I wrote 20-30 years ago and I have no
>idea why and what the code was written for!!!! even after reading each
>line of the code!!!!

This is what got me interested in literate programming.

Axiom was written at IBM as "research code", mostly by people trying to
get a PhD. I wrote bits and pieces of the internals but didn't bother
to document anything, especially since I write "dirt simple code".

Fifteen years later I'm looking at my own code. I know what it does.
I can even tell you what bytes the compiler will lay down in memory.
I know the code is needed since the system fails if I remove it.

But I have no clue WHY I wrote it.

The person who wrote the code failed to communicate with the person
who maintains the code. I have the misfortune of being both people.

I understand the strong opposition to writing good documentation at any
level. Especially when writing code; it just seems wasteful to "state
the obvious".

One non-obvious side effect of doing literate programming is that the
code quality improves a LOT. As Bill Hart said:

Another thing I've been enjoying lately is literate programming.
Amazingly it turns out to be faster to write a literate program
than an ordinary program because debugging takes almost no time.

I fear that we're going to have the same approach as the physicists.
"New theories get accepted when the previous generation dies out."

Fortunately statistics show that programmers retire into management
at age 35 so we won't have to wait that long. If there is any justice,
the managers will have to hire noobs to maintain code they wrote so
they get to listen to the noobs trash talk about their code. :-)

Tim Daly



--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Gary Johnson]

Hi folks,

I suspect I'm the Gary that Tim thought he was referring to since I've
posted on several of his other LP-related threads (though not this one
until now). I'm reading along and enjoying the back and forth as usual, but
I'm sorry to say that I don't have much to add to this philosophical
swordfight.

As I've stated on other threads, I find LP quite useful to me, both in
helping me remember later what my old code does (and WHY I wrote it that
way in the first place) as well as helping me to write clearer and more
parsimonious code in the first place (since I don't want to document a
crazy web of unnecessary complexity if I can avoid it). All in all, my
personal LP journey has been an interesting and reasonably productive one.
And of course, using an expressive functional language like Clojure does
allow me to keep my code snippets shorter and more isolated from one
another. All good things for LP as well.

I know that Tim likes to poke the mailing list occasionally and remind
people that LP is the bee's knees and that they should really get on board
with it. I also know that without fail one or more folks will quickly
respond that LP doesn't provide enough value above docstrings, inline
comments, autogenerated API docs, and the occasional blog post to invest
the necessary time in developing new LP-mindful workflows. And, of course,
someone will inevitably chime in with the rally cry "clear code doesn't
need documentation".

I understand that really embracing LP does require relearning how to
program in several fundamental respects, AND it makes it quite difficult to
use many of the developer tools many folks in the Clojure community have
come to rely on. This makes the task appear somewhere between challenging
and onerous to many programmers (or so I would imagine from following Tim's
threads over the past year). However, (speaking only for myself here) I
think the maintenance benefits often outweigh the upfront investment for
any piece of software I intend to keep around for more than a few months.
So for me, it's a net good. For some folks it's not. I get that. Enough
said.

But really, at the end of the day, I'm just getting tired of listening to
people razzing on LP for the reasons listed above. There ARE good tools out
there for doing this kind of programming. People just have to invest time
and energy into learning them. I regularly cite Emacs' Org-mode as
providing most everything you might need to comfortably create LP programs
without even writing one line of LaTeX or XML (if you're allergic to those
languages). Obviously, as Tim points out, it's an almost trivial assignment
to roll your own tangle and weave scripts in whatever language you like
(and I've tried that route too). So guys, if you don't like the ideas
behind LP or just feel like it is too much of a hassle to use, then I
completely understand that you don't want to use it. But could we maybe
call a truce on this mailing list on the topic?

Perhaps instead of constantly being pulled into philosophical arguments,
those of us who actually do enjoy exploring LP could then use this forum to
discuss amongst ourselves what tools or references we are finding useful in
our journey. Clearly some folks (Gregg included) are churning out some
pretty neat looking tools to make LP easier to do in the Clojure world. I
for one would love to see more lively discussion around that and not feel
like we're just bear-baiting whenever we mention the forbidden paradigm of
Literate Programming.

My 2c,
~ (the actual) Gary

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Mars0i]

On Thursday, May 22, 2014 4:05:58 PM UTC-5, Gary Johnson wrote:
>
> Hi folks,
>
> I suspect I'm the Gary that Tim thought he was referring to since I've
> posted on several of his other LP-related threads (though not this one
> until now).
>

I cede the name "Gary" to Gary.


> But really, at the end of the day, I'm just getting tired of listening
> to people razzing on LP for the reasons listed above.
>

For my part, I have never intended to criticize LP per se. When it sounds
as if someone is arguing that everyone should use LP all the time (or
something similar), I sometimes object.

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Gary Johnson]

On Thursday, May 22, 2014 6:20:39 PM UTC-4, Mars0i wrote:
>
> On Thursday, May 22, 2014 4:05:58 PM UTC-5, Gary Johnson wrote:
>>
>> Hi folks,
>>
>> I suspect I'm the Gary that Tim thought he was referring to since I've
>> posted on several of his other LP-related threads (though not this one
>> until now).
>>
>
> I cede the name "Gary" to Gary.
>

No worries. You can be Gary too if you'd like. It's a passable name, all
things considered. ;-)


>
>
>> But really, at the end of the day, I'm just getting tired of listening
>> to people razzing on LP for the reasons listed above.
>>
>
> For my part, I have never intended to criticize LP per se. When it sounds
> as if someone is arguing that everyone should use LP all the time (or
> something similar), I sometimes object.
>

Hey, point taken. I'm certainly not out to force LP on anyone. I'm just
here to soak up advice from the folks who have been using it for awhile.
I'm happy keeping the kool-aid to myself, so to speak. :-P

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[d***@axiom-developer.org]

>I know Clojure doesn't have all the documentation many would like, but Tim,
>this bit of info is in readme.txt, and the first 3 lines of every source
>file from the library :-)

Touche! +2 points to you!

I love it when my oh-so-noisy self gets skewered by facts! :-)

Tim Daly

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to ***@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+***@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+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.