Literate Programming
da...@axiom-developer.org
On Fri, 2011-12-23 at 03:33 -0800, Adam Getchell wrote:
> Having received the benefit of your kind reply, I must confess to a
> puzzlement which has vexed me ever since I read your missive. It is
> this: how should I have read it so as to receive some knowledge or
> insight with which I had not formerly possessed in the moments prior?
> For in truth I have not been able to discern its helpfulness thereby.
Methinks thou hast conflated the spirit of literate programming,
intended as a communication medium between fellow traveling souls
on this dark road with the substance of the task involving the
choice of conveyance and walking stick. Replying to the former
'twas I, whilest thou was't addressing the latter.
We did pass by in our respective darkness.
Forgive me for lacking light to guide your chosen path.
I mistook your destination for mine own, a grievous fault,
one to which I am ever prone.
> Clearly, as a craftsman of computer algebra tools yourself, you
> must agree that the selection of implements is of some import,
> lest you abandon that enterprise entirely and use Mathematica
> instead.
Truly I do quake at the co-opting possible should the fair winds
drift the conversation from the soul of the art to the choice and
heft of tooling. Like the goodly Saint Alexander [1] we need to
seek the order which contains life. What doth make a program live,
or the building alive, is not to be found in the tooling but in
ourselves. We must eschew the pernicious present practice lest
we find our creation among the dead and dying on Sourceforge.
I have chosen minimal tools for my algebra opus. Latex for
smithing and tangle for forging. I find no need for any other
save the, as yet unrealized, potential of graphing tools.
'Tis not the tools but my poor craftsmanship that constrains
the quality of the work.
>> The combination of literate + TDD seems forbidding
> Are you finding it hard to explain why you wrote a test?
In this platonic exchange is made apparent my confusion. The
dross of failures that skins the molten and fluid gold of your
smelting needs but a few words. "Lo, this might arise at the
boundary of my creation." That the dross needeth explaining
to the Smithy new to your endeavor, yet still it certainly
can be conveyed in flowing natural language.
Sharing the tale of the journey, the wonders of the vision, and
the pleasures of final offering depends not on the choice of pen
but on the craftmanship of language. That the gentle reader
delight in your creation and sing its praises, see the vision,
and dedication lifeblood to its continuance is all. That we might
achieve such essential Quality [2] with Clojure is the dream.
Sir Tim Daly, Elder of the Internet
[1] Alexander, Christopher
"The Nature of Order: The Phenomenon of Life"
2002 ISBN 0-9726529-1-4
[2] Persig, Robert
"Zen and the Art of Motorcycle Maintenance: An Inquiry into Values"
1974 ISBN 0-553-27747-2
daly
> Like this? http://brighterplanet.github.com/flight/impact_model.html
My first reaction, after the first reading was "almost ok".
The task is reasonably mathematical so it seems useful to
show the equations. Unfortunately, at the end, I have to ask
myself the "Hawaii question".... If someone sent me off to
hawaii (so I couldn't talk to the author), would I know enough
to maintain the program?
Well, maybe.
I really liked that they embedded a link to the impacts web page.
That placed the problem in context.
And I especially liked
"A multiplier to account for the extra climate impact of
greenhouse gas emissions high in the atmosphere.
Use 2.0 after Kollmuss and Crimmins (2009)."
I was unhappy with:
=begin
FIXME TODO date should already be coerced
=end
Really? Coerced to what, by what, for what reason, in what format?
I was just hired and asked to solve this problem.
=begin
FIXME TODO deal with cities in multiple countries that share a name
Tried pushing country, which works on a flight from Mexico City to
Barcelona, Spain because it does not include flights to Barcelona,
Venezuela BUT it doesn't work if we're trying to go from Montreal
end up with flights to London, United Kingdom. Also pushing country
breaks addition of cohorts - all 'AND' statements get changed to 'OR'
so you end up with all flights to that country e.g. WHERE
origin_airport_iata_code = 'JFK' OR origin_country_iso_3166_code =
'US'
=end
So why isn't this part of the dialog? Why does it break? Is the
database improperly structured? Do we need a schema change? Or
do we need program logic to handle this case?
The use of FIXME is horribly jarring. Get rid of it.
Think of a calculus textbook where the source code is the equations.
Now imagine that in the middle of an equation you see the above
comment. Something like:
area = \sum_i^j x*3 =begin FIXME might be x^4 =end * y
The editor-in-chief would never let the above equation get into
the text. The FIXME should be discussed as part of the prose
rather than "in the equations".
I don't think it would pass the code review phase with these
"FIXME" things hanging around. FIXME is the programmer's internal
dialog. Discuss the issue in the text as though you were talking
to someone other than yourself. Odds are good this is where a
design mistake (e.g. in the database schema) or a program bug lurks.
The meta-issue is distinguishing "communication" from "documentation".
Literate programming is about communication, not documentation.
Write with your audience in mind and assume that the audience is
NOT your shower committee (a shower committee is the group of people
you talk to in the shower who are not really there).
This example really skates along the border. Overall I think it is
wildly better than most examples I've seen. I'd much rather maintain
this program with the text than without it. I'd certainly place it
on the high side of the curve.
Tim Daly
nchurch
> You can see how they handle it (from a Ruby-centric perspective) here: https://github.com/brighterplanet/numbers/blob/gh-pages/_posts/2010-12-02-github-pages-rocco-and-rake-file-tasks.markdown
(The original thread seems to have disappeared; it can be found here:
http://groups.google.com/group/clojure/browse_thread/thread/7f31a8e7aa98a547/5562eb25b9d70365?lnk=gst&q=Lithub#5562eb25b9d70365.)
This does seem to be a good way of doing a Lithub. For that matter,
there is the recent release of Clojure fs utils with Marginalia docs
at http://raynes.github.com/fs/
I'd say this kind of thing needs really only two steps to be a full
Lithub. One, this should be the \main way of viewing code, i.e. in
place of https://github.com/Raynes/fs. There does seem to be a
certain amount of customization of Github possible from the
Brighterplanet example, so maybe a Marginalia-centric Lithub within
Github is possible. Maybe it would even be possible to give three
views of the same material: code and docs side-by-side, docs with
links to code, and vice-versa.
The second step is a matter of search-engine optimization----something
I know very little about, I have to admit. Look at this line in the
fs utils Marginalia, for instance:
Return the base name (final segment/file part) of a path.
(defn base-name
[path]
(.getName (file path)))
All the keywords you need to find that function are there; it even
provides three alternatives! If I were searching off the top of my
head, I'd probably Google: return file part of path in Clojure. But
this returns a mess of links that don't really lead to that function;
the Marginalia line doesn't even show up in the first few pages of
results (granted, it's fairly new).
Imagine if that kind of thing \were the first link, every time.
Consider how much time people spend every day looking for library
functions----any improvement in that process would be a big
productivity and coding-flow gain. Having independent HTML anchors
for each function in a Marginalia page would be a start----much
simpler than convincing Google to rank specific functions first. If
the Google-whispering proves to be too difficult, the next best thing
would be optimizing search within the Lithub sites, so that the top
links are always to Clojure library functions and how to call them,
without any distraction.
nchurch
structure entry points into a huge codebase like Clojure----how to
present simplifications and toy examples, etc., and walk the reader
through it. I think the other two things are such big wins, though,
that this third concern can take a back seat.
On Dec 26, 12:13 pm, nchurch <nchubr...@gmail.com> wrote:
> > Like this? http://brighterplanet.github.com/flight/impact_model.html
>
> (The original thread seems to have disappeared; it can be found here:http://groups.google.com/group/clojure/browse_thread/thread/7f31a8e7a....)
> This does seem to be a good way of doing a Lithub. For that matter,
> there is the recent release of Clojure fs utils with Marginalia docs
> I'd say this kind of thing needs really only two steps to be a full
> Lithub. One, this should be the \main way of viewing code, i.e. in