On Friday, April 19, 2013 9:37:52 PM UTC-4, da...@axiom-developer.org wrote: > > TL:DR > > Write ideas for humans around your code or it will die. > Explain, don't document. > > Excellent post, Tim. Thanks for writing it all up.
Though, I tend to think that "documenting" is the same as "explaining" (what good is documentation if it doesn't explain?). > I mean that you need to write words that communicate IDEAS from > human to human. Real sentences with real words that you would say > to someone looking at the code. > If you don't communicate the idea embodied in a piece of code in > words humans can understand, you are writing dead code for yourself. > > Yes. > If you want your code to LIVE, write WORDS for other HUMANS. Lots of > words. More words than code. Think of the difference between a math > reference textbook and a regular math book. Words. > > One minor point to add: It's easy to write too much. To meander. Concision is hard. > I strongly recommend literate programming but feel free to ignore that. > Write words. > > Hm. Maybe I should ask this off-list, but, in a nutshell, is literate programming: 1. put possibly-out-of-order specially-marked (with an id) code snippets throughout your doc, 2. also put an *ordered* listing of all the id's somewhere in your doc, 3. use tools to find that ordered list of ids, then extract the snippets, put them in order, and glue them all together so they can be compiled/run? Thanks, ---John -- -- 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/groups/opt_out.
