Tim, >From my point of view there are at least a few things that seem clear:
1. I think that Gregg Reynolds and I agree on a lot, but I would add to his remarks that there is almost always a human audience for source code, as well as the compiler/interpreter. Sometimes, the audience is just the originally programmer, perhaps at a later date. (If I missed something, Gregg, sorry, but I don't think you disagree, anyway.) 2. Since Clojure is a general-purpose tool, Clojure source code has no single kind of human audience for the code. In general, I do different things with comments, or with my coding style, depending on whether I expect that I will be the only maintainer of the code, or expect that others with whom I'm collaborating will need to interface with it, for example. Further, I think about the skill levels and background of those who will read the code. And I think about what they would want to do with it. And then I make decisions that involve tradeoffs between competing desiderata. 3. There is a tradeoff between the desire to see a lot of code at once, without a lot of text cluttering it up, and understanding what the code is doing. Comments hurt the former but can help the latter. The same thing goes for literate programming, but--it depends on your goals and your human audience. 4. Two examples to convey the context-dependence of appropriate configuration schemes: A. One time I wrote a small but slightly complex bit of code (in Perl, not Clojure). I could see that it would be confusing, if someone just started reading the code at an arbitrary place. But I also knew the ability of the other programmers I worked with, and I knew that if they started reading at one particular function, they would be able to figure out most of the rest. I provided text that explained what they wouldn't be able to figure out. About six months after I left the company, one of the programmers contacted me and asked me to explain the program; he had to make a modification. I told him to look at such and such document, which mainly said "Start reading the code at such and such point, and understand these few other things." He did, and that was all he needed. If I wrote more documentation, I would only be duplicating the information that was already there in the source code, and that would be apparent for the kind of people who would read it. In fact, if I provided *more* documentation, I doubt that the other programmers would have read it. They would have just looked at the source. B. Another example. I generally don't like the idea of LP. That is to say, I like the idea of people who want to be able to use it, using it, but I don't want to use it, usually. And the reason that I don't want to use it is not simply that I don't want to bother writing it. It's that I want the ability to use simple tools and I want to have relatively uncluttered source code. (I could use LP and have uncluttered source much of the time, but only by using special tools.) In my current main project, there is source code that implements the central functionality of the application, and there are rather complex configuration files. I write documents to describe the central functionality source code, so that someone who wants to hack on it will know where to start and where to look. I have to trust that they will know or will be willing to learn Clojure, because otherwise I'd have to explain too much. However, the configuration files should be modifiable by people who won't understand the guts of the program, and yet, they are in Clojure, and would be pretty unintelligible to someone who merely understood in general what the program was supposed to do. (I may create a DSL for the config files, but all that will do will be to get rid of a few parentheses. The information in the config files won't be expressed significantly more succinctly.) For the first time I'm thinking of using LP. It would be perfect for the config files, and in fact, any other way of documenting the config files will probably be inadequate. Interspersing explanations with the configuration code is precisely what's needed. -- 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.
