Wednesday, November 06, 2013

Code documentation

"I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature."
—Donald Knuth, “Literate Programming

Inspired  roxygen

Further quotes from Literate Programming by Donald Knuth:
"first [...], I thought that I would be designing a language for “top-down” programming, where a top-level description is given [...] and successively refined. On the other hand I knew that I often created major parts of programs in a “bottom-up” fashion, starting with the definitions of basic procedures and data structures and gradually building more and more powerful subroutines. I had the feeling that top-down and bottom-up were opposing methodologies: one more suitable for program exposition and the other more suitable for  program creation.  But after gaining experience with WEB, I have come to realize that there is no need to choose once and for all between top-down and bottom-up, because a program is best thought of as a web instead of a tree. A hierarchical structure is present, but the most important thing about a program is its structural relationships.
[...]
Thus, WEB may be only for the subset of computer scientists who like to write and to explain what they are doing. "

No comments: