I hesitate to extend this unpleasant thread, but here's a relevant post that definitely takes a stand on the commenting issue:
http://steve-yegge.blogspot.com/2008/02/portrait-of-n00b.html As usual with Steve, it's a funny post, so I hope nobody takes it too seriously :) Hugh On Wed, Dec 31, 2008 at 9:49 AM, Tom Ayerst <tom.aye...@gmail.com> wrote: > "'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 -~----------~----~----~----~------~----~------~--~---
