Pathologically Eclectic Rubbish Lister | |
PerlMonks |
comment on |
( [id://3333]=superdoc: print w/replies, xml ) | Need Help?? |
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.
In reply to Re^3: An Introduction to Literate Programming with perlWEB
by BrowserUk
|
|