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 _______________________________________________ Axiom-developer mailing list Axiom-developer@nongnu.org https://lists.nongnu.org/mailman/listinfo/axiom-developer