I think we all know this, but just to make sure the point is clear (in some of the dicussion here, it doesn't seem that it is), the alternatives are not only:
(a) Source code with docstrings (or fancy formatted docstrings with links, etc.) and sparse comments, but no other explanatory text anywhere. (b) Literate programming. Of course long chunks of text are needed to explain algorithms, motivation, paths not taken, etc. Literate programming requires that those chunks be inserted into the source file, and that you have to run the source file through a filter to get rid of them. Here's how I have been working lately: Early in the process of developing a section of code, I often insert long comments to explain what I'm doing or what I intend to do, etc. Like literate code, but with comment characters in front of it. Eventually, I look at the source file and think, "That long comment is cluttering up the code. I have to scroll down to often to see what's going on in the code." Then I put the long comment into a separate file, (perhaps a file that already contains some explanatory text), strip the comment characters, and maybe add some markdown or write some additional text. I leave some essential comments in the text, or put information into docstrings if it seems appropriate. The point is that these days, at least, I don't *want* a lot of text in the file that contains my source code, even though I think that explanatory documentation is *very* important, and even though I'd guess that I've written more of it per line of code than the average programmer. But that's me. Others find LP extremely beneficial, and I support that strategy for those who like it. (The desire to be able to see a lot of code at once is also one reason why C-style code formatting is undesirable in a lisp language.) -- 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.
