On Tue, Apr 29, 2014 at 7:44 PM, Phil Hagelberg <p...@hagelb.org> wrote:
> On Saturday, April 26, 2014 9:21:26 PM UTC-7, Mars0i wrote: > > I like the general idea of the Valentin's proposal, but I don't > > understand every bit of it. It sounds complicated. Personally, I'd > > rather see something that's relatively simple, and good enough, than > > something that's perfect but unwieldy. If it's too difficult, people > > won't use it, or they'll waste time, or feel that the Clojure > > community expects them to spend too much time on something that > > detracts from what's important. > > Double-inc[1] on this. Clojure needs people who care about documentation > far more than it needs another documentation system. Don't try to apply a > technical solution to a social problem. > Double-dog dinc. Having followed this thread I hazard a few reminders of the obvious. Code *is* documentation. Programmers don't like to write "documentation" - it's hard enough to write good code, and then you want me to translate my code into clear simple concise English? (Are you nuts? Learn to read code!) Writing good documentation and writing good code are distinct skills that are very rarely found in a single person. Good documentation is expensive. "Good" means "good enough". Less obvious: there are at least two distinct notions of documentation in play. One is the code: self-documenting documentation. The other is arguably meta-documentation: English (usually) prose *about* the code - which means, about the self-documenting documentation. Controversial: literate programming is a bad, bad, bad idea. There is a reason it has never caught on. Ever try to hack Tex? Did Knuth's "literate" code help? Maybe; but people routinely tackle systems that are just as complex without the added burden of tangle and weave, etc. Many years ago I had to do maintenance work on a banking system written entirely in S/370 assembler. It was a pain, but it was doable. Literate programming would have made it far worse, in my opinion. Would it be easier to hack TeX if it had been written without the lit prog cruft? In my view the answer is (probably) yes. (Note that, until relatively recently, (XeTeX and LuaTex) there was almost no work that built on TeX to make new stuff - which is what Knuth had hoped for.) But the more critical point is that TeX was (mostly) a one-man show. Literate programming fine for that, but is utterly, irredeemably, terminally unsuitable for the sorts of projects that work in the open source world - lots of different people, scratching lots of different itches, with lots of different opinions about the Way the World Ought To Work. I can see no reason to think that "literate code" is in any way immune to the problems that inevitably afflict any successful software project - bitrot, feature creep, over-engineering, under-specification, gradual divergence between descriptions of the system and what it actually does, pressure to just make the damn thing work (as opposed to "doing it right"), etc. etc. etc. My heart sinks whenever I see a project that looks good but is implemented in "literate" programming. If I really like it and want to bang on it, the first thing I will do is terminate the literate stuff with extreme prejudice - give me the code, please, and the minimal amount of local commenting. I'll read the "literate" docs, but will never code the stuff. The one thing that I think would be genuinely useful and developer friendly with respect to Clojure is a means of making type signatures explicit. Clojure may be dynamically typed, but everything has an intended type, and I would like to see it. I'm thinking of something along the way Haskell and other languages express type sigs. The paradigmatic example is factorial (or fibonacci). So given a factorial function "fact" I want to be able to write something like (type-sig fact) and get something like "Int -> Int". -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.
