(Just as an aside, there is a conference called "Write the Docs".
see http://writethedocs.org)
> The only way to find out is to read the code - that is, the algorithm,
> not just the names. (This code was documented, by the way.) In my
> experience clashes between the natural language semantics of function
> and var names on the one had, and the jobs they actually do on the
> other, is pervasive, and I see little chance that this will ever
> change. Not because programmers are dumb but because coming up with
> expressive and accurate names is hard and time consuming.
Imagine if a physics professor said that the only way to understand
anything was to read the formula... not the text "documentation". In
some sense it is true that the formula (i.e. code) is "truth" but
everyone EXPECTS that the surrounding text is accurate and up to
date. Otherwise, there would be a LOT of people telling the author
about the mismatch. Why don't we expect the same in programming?
Writing "just the code" is about as effective as a book containing
only the physics equations with no text, correct but opaque.
We CAN have accurate, up-to-date, documentation. It requires changes
to the way we write software. In particular, clear and accurate
documentation should be a REQUIREMENT for every change checked into
a repository. We have "code reviews" to check for bad code. The code
review should also check that the code mirrors the documentation.
This doesn't require a tool, per se, but a good tool would help
others navigate among the ideas.
> Which leads to a larger point: a genuine improvement in the Clojure
> documentation situation requires (IMHO) some Deep Thinking about the nature
> of code, the relation between code (text) and algorithm, natural language
> text, expressivity, programmer practices, etc. In other words, we should
> follow Rich Hickey's example - I take it that Clojure itself emerged from
> some Deep Thinking about the nature of computation, programming language
> design, etc.
Any software designer worth his title would first collect requirements.
Then each of the proposed solutions can be checked to see if they
fulfill the requirements. Most of the posted ideas don't begin to
fulfill the requirements. Good documentation is not a new idea.
It has been thought about deeply before.
I know that some people dismiss literate programming "by fiat" (aka
it is worthless..., it can't work..., it adds nothing..., etc) but
surely Knuth is a "Deep Thinker" on par with Rich Hickey.
Knuth said:
"I believe that the time is ripe for significantly better
documentation of programs, and that we can best achieve this
by considering programs to be works of literature. Hence, my
title "Literate Programming".
Let us change our traditional attitude to the construction
of programs: 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."
Knuth said:
"Yet to me, literate programming is certainly the most important
thing that came out of the TeX project. Not only has it enabled
me to write and maintain programs faster and more reliably than
ever before, and been one of my greatest sources of joy since
the 1980s -- it has actually been indispensable at times. Some
of my major programs, such as the MMIX meta-simulators, could
not have been written with any other methodology that I've ever
heard of. The complexity was simply too daunting for my limited
brain to handle; without literate programming, the whole enterprise
would have flopped miserably.
If people discover nice ways to use the newfangled multi-
threaded machines, I would expect the discovery to come from
people who routinely use literate programming. Literate programming
is what you need to rise above the ordinary level of achievement"
Bill Hart, on the SAGE Mailing list wrote:
"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."
Ross Williams, in the FunnelWeb Tutorial wrote:
"The effect of this simple shift of emphasis can be so profound as
to change one's whole approach to programming. Under the literate
programming paradigm, the central activity of programming
becomes that of conveying meaning to other intelligent beings
rather than merely convincing the computer to behave in a
particular way. It is the difference between performing and
exposing a magic trick."
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to [email protected]
Note that posts from new members are moderated - please be patient with your
first post.
To unsubscribe from this group, send email to
[email protected]
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 [email protected].
For more options, visit https://groups.google.com/d/optout.
