(Just as an aside, there is a conference called "Write the Docs". see http://writethedocs.org)
> The only way to find out is to read the code - that is, the algorithm, > not just the names. (This code was documented, by the way.) In my > experience clashes between the natural language semantics of function > and var names on the one had, and the jobs they actually do on the > other, is pervasive, and I see little chance that this will ever > change. Not because programmers are dumb but because coming up with > expressive and accurate names is hard and time consuming. Imagine if a physics professor said that the only way to understand anything was to read the formula... not the text "documentation". In some sense it is true that the formula (i.e. code) is "truth" but everyone EXPECTS that the surrounding text is accurate and up to date. Otherwise, there would be a LOT of people telling the author about the mismatch. Why don't we expect the same in programming? Writing "just the code" is about as effective as a book containing only the physics equations with no text, correct but opaque. We CAN have accurate, up-to-date, documentation. It requires changes to the way we write software. In particular, clear and accurate documentation should be a REQUIREMENT for every change checked into a repository. We have "code reviews" to check for bad code. The code review should also check that the code mirrors the documentation. This doesn't require a tool, per se, but a good tool would help others navigate among the ideas. > Which leads to a larger point: a genuine improvement in the Clojure > documentation situation requires (IMHO) some Deep Thinking about the nature > of code, the relation between code (text) and algorithm, natural language > text, expressivity, programmer practices, etc. In other words, we should > follow Rich Hickey's example - I take it that Clojure itself emerged from > some Deep Thinking about the nature of computation, programming language > design, etc. Any software designer worth his title would first collect requirements. Then each of the proposed solutions can be checked to see if they fulfill the requirements. Most of the posted ideas don't begin to fulfill the requirements. Good documentation is not a new idea. It has been thought about deeply before. I know that some people dismiss literate programming "by fiat" (aka it is worthless..., it can't work..., it adds nothing..., etc) but surely Knuth is a "Deep Thinker" on par with Rich Hickey. Knuth said: "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. Hence, my title "Literate Programming". Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do." Knuth said: "Yet to me, literate programming is certainly the most important thing that came out of the TeX project. Not only has it enabled me to write and maintain programs faster and more reliably than ever before, and been one of my greatest sources of joy since the 1980s -- it has actually been indispensable at times. Some of my major programs, such as the MMIX meta-simulators, could not have been written with any other methodology that I've ever heard of. The complexity was simply too daunting for my limited brain to handle; without literate programming, the whole enterprise would have flopped miserably. If people discover nice ways to use the newfangled multi- threaded machines, I would expect the discovery to come from people who routinely use literate programming. Literate programming is what you need to rise above the ordinary level of achievement" Bill Hart, on the SAGE Mailing list wrote: "Another thing I've been enjoying lately is literate programming. Amazingly it turns out to be faster to write a literate program than an ordinary program because debugging takes almost no time." Ross Williams, in the FunnelWeb Tutorial wrote: "The effect of this simple shift of emphasis can be so profound as to change one's whole approach to programming. Under the literate programming paradigm, the central activity of programming becomes that of conveying meaning to other intelligent beings rather than merely convincing the computer to behave in a particular way. It is the difference between performing and exposing a magic trick." -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.