On Wed, May 21, 2014 at 4:39 PM, Mars0i <marsh...@logical.net> wrote:
> 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.) > I agree; whoever writes the code automatically forms an "audience" of one. I guess I would say "reader/responder". > > 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. > Exactly. Conclusion: it's hard, maybe impossible, to generalize about what all code should look like. Maybe it's essentially pluralistic. > > 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. > Yep; there's always a point of diminishing returns. I find that in developing code (or trying to understand others' code) I often take extensive notes and sometimes try to mentally "improve" what I deem sloppy or hard-to-read by writing a clear description of it, or just expressing it in different language. But once I get comfortable with the code I don't often return to my documentation. ... > 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. > I agree, that's a case where monolithic LP is entirely appropriate. Ditto for APIs and unit tests; maybe also for simplified examples of API usage expressly designed for training. -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.
