On Fri, May 2, 2014 at 4:00 AM, Val Waeselynck <val.vval...@gmail.com>wrote:
> > That is NOT what I said. Please go back and read my response more >> carefully. >> > > Apologies, guess I disagree only with Gregg on that point then. > I guess this illustrates a point that is usually overlooked: no matter how good your documentation is, somebody will always misread it. Which gets back to the point I was trying to make: the ultimate source of authoritative information about what the code does is the code itself. It does not follow that the names used in the code are reliable guides to what the code means. Consider the following (mangled from http://en.wikibooks.org/wiki/Clojure_Programming/Examples/Lazy_Fibonacci): (def factorial ((fn rfact [a b] (lazy-seq (cons a (rfact b (+ a b))))) 0 1)) Obviously not a factorial function; to know what it is, you have to read the code, which expresses an algorithm (in this case fibonacci). Something this extreme probably doesn't happen very often, but something very like it happens all the time. Yesterday I was working through some Java code called "fooReader". The docstring said it inherited from XMLReader. It did not, rather it inherited from XMLFilter. Which in turn inherits from AbstractWriter. So what is it, a Reader, Filter, or Writer? 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. 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. -Gregg -- 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.
