"'Redundant comments are useless' is the mantra of the dilettante, the amateur, and the cowboy."dilettante, the amateur, and the cowboy"", ouch. Redundant comments are... redundant (hence the name), and a support overhead and a source of misunderstanding if they are not updated in line with the code. If you are writing code that will be read by people familiar with the language and idioms and using meaningful names then a small number well targeted comments are usually enough (Personally I do like a comment on each function saying what it is for, doc strings look like the right solution for this).
Having said that; redundancy is a matter of context and I could use more comments and meaningful variables in example code, I am acquainted with Scheme so I can work my way through, but it is easy to get lost in the homogeneous syntax and unfamiliar constructs and idioms. When trying something new the fewer gumption traps the better and it is important to make sure information is to hand, this could be done through repetition or by the application of a little more indirection; earlier in the thread Mark asked if people would be aware of how to set up a clj script, good question and a link to the place that explains how, when you need it, would be very useful. Personally I don't think we need standards and stuff, what we need is some more "code with training wheels" (lots comments and links taking you through it very gently). That is not really Rich's job, he is to busy inventing the thing, I think Mark's evolving example is great and a few more like it covering other areas would be fine things and I hope to add to them myself when I am a bit more familiar with Clojure. That was a bit more rambling than planned. Happy New Year Tom 2008/12/31 Simon Brooke <still...@googlemail.com> > > On Dec 29, 3:15 am, Rich Hickey <richhic...@gmail.com> wrote: > > On Dec 28, 8:13 pm, "Mark Volkmann" <r.mark.volkm...@gmail.com> wrote: > > > > > I'll not argue for making code harder to read, but I have to object to > > most of your example. > > > > Making something 4x longer does not make it easier to read. > > > > Redundant comments are useless. > > This is the excuse continually trotted out by people too lazy to > comment, or who think themselves superior to merely mortal programmers > who have to work in teams and actually communicate with people. > Redundancy in communication is almost never redundant; think of it as > a checksum. > > ... > > 'Redundant comments are useless' is the mantra of the dilettante, the > amateur, and the cowboy. > > --~--~---------~--~----~------------~-------~--~----~ 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 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 -~----------~----~----~----~------~----~------~--~---