> Adding complexity and weaving heapings of prose in amongst the code > isn't going to make the developer that wrote the above rewrite it in a > better way. You'll just end up with more bad documentation getting in > the way of what the code actually does. Bad documentation is worse than > no documentation. At least with no documentation, the code doesn't > lie.
Bad documentation should have to leap the same hurdles as bad code. Code review ought to be able to push back against bad documentation just as easily as it screams at bad code. There is the famous "WTFs per minute" cartoon that can be applied to documentation. Doing regular doc reviews might provide full employment for English majors :-) In fact, working on a WTF code review social process in Clojure might be the most effective step toward better code and documentation overall. Of course, this would have to be instituted by Rich and company since they control the sources. We could post code snippets (ref my prior post) which need explanation and do a "community documentation upgrade" on the Clojure sources. Tim -- 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.
