Re^3: An Introduction to Literate Programming with perlWEB

Architects don't design bridges; civil engineers do.

Tell that to the architect Norman Foster who designed the The Millau Viaduct (in conjunction with a French Structural Engineer).

Stress calculation are obviously done, and checked and recorded and are an integral part of the overall design and documentation--but they don't do the calculations on the backs (or fronts) of the blue-prints. You don't put the two in the same document.

And while the contract you sign may not have all those lovely footnotes,

Exactly! You don't put them all in one document.

I strongly support project documentation--what files, modules and libraries exist (and where), and what they do; the names of the public interfaces and their parameters; and their purpose--but you don't need to include the names of the internal variables, constants or explain how sort works.

It's all about not mixing different concerns together; Not repeating effort (the DRY principle); and not creating unnecessary artificial dependencies (the decoupling principle).

Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.

"Science is about questioning the status quo. Questioning authority".

In the absence of evidence, opinion is indistinguishable from prejudice.

"Too many [] have been sedated by an oppressive environment of political correctness and risk aversion."

Comment on Re^3: An Introduction to Literate Programming with perlWEB

Replies are listed 'Best First'.
Re^4: An Introduction to Literate Programming with perlWEB by swampyankee (Parson) on Jan 13, 2009 at 18:30 UTC
The drawing isn't the document; it's a part of the document, like Chapter XIV in Moby Dick. Maybe the difference is largely nomenclature, in that you're viewing the drawing as a product, analogously to a computer program, where I don't: it's a step, used to describe a part's geometry and no more a complete part description than "steel." On a drawing, one wouldn't say "bolt" without quite a lot of further information, like the size. From here on was added in an update. Oddly, I agree with many of your issues with LP, in that it adds a pre-processing layer, and even adds the complication of re-ordering code. I tend to view it as a very elaborate scheme of commentary, which may be a complete misinterpretation of its goals. Information about American English usage here and here. Floating point issues? Please read this before posting. — emc	[reply]
Re^5: An Introduction to Literate Programming with perlWEB by BrowserUk (Patriarch) on Jan 13, 2009 at 19:09 UTC
you're viewing the drawing as a product, analogously to a computer program, where I don't: As a one-time indentured draughtsman and qualified Mech.Eng, I can tell you that your interpretation is discordant with the way engineers view blueprints. Each blueprint has its own document no.; modifications history; title; keys; etc. They are "documents" in their own right. And in combination with materials lists--which sometimes are included on the drawings, they can be a complete specification for the manufacture of the product. Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error. "Science is about questioning the status quo. Questioning authority". In the absence of evidence, opinion is indistinguishable from prejudice. "Too many [] have been sedated by an oppressive environment of political correctness and risk aversion."	[reply]