All right, I'll give it a try, here are some thoughts : I think it's too hard make precise requirements for advanced features in advance; I'd rather find a way to let usage drive us in the right direction. However, there are a few principles that we know will be wise to follow :
- encouraging separation of concerns - avoiding duplication of logic And indeed as a programming language, Clojure follow these very well in many respects. Applying these to the topic of documentation, I think it's a good idea to make the documentation system/process separate the concerns of writing quality code and making understandable. That seems to make a case towards documenting with tests/examples/schemas and against literate programming (was that your point, Gregg?) - and maybe also against using types for documenting, but that's really my own personal feeling and I don't have any evidence for it. Avoiding duplication of logic seems to encourage the overlapping of tests and documentation examples in code, so something close to what lein-midje-doc currently offers. Is that OK for everyone? Le vendredi 2 mai 2014 16:16:24 UTC+2, Gregg Reynolds a écrit : > > On Fri, May 2, 2014 at 4:00 AM, Val Waeselynck > <val.v...@gmail.com<javascript:> > > 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.
