Re: [Axiom-developer] Literate Programming

[daly]

On Sat, 2011-12-24 at 12:56 -0600, Jay Edwards wrote:
> 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