Simon Brooke wrote: > 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.
I used to subscribe to this thought. Now I don't. I used to put useless comments in my code. Now I don't. Comments should be appropriate to the persons who will read it. Copious comments are appropriate in tutorials and SDK examples, etc. But for production code, I'll comment only if I feel that *I* will need it when I come back to the code later. I do not think I'm superior to anybody else. But a certain level of competence is assumed in any project. My assumption is that after I'm gone from a project, whoever replaces me should be at least as competent as I am. If not, that's not my problem. > Redundancy in communication is almost never redundant; think of it as > a checksum. When you listen to someone talking naturally and > explaining something, you'll almost always find they express the same > idea multiple times in different forms of words. Why? It makes certain > that it is clear. There is a difference between code and other forms of communication. If the code is not clear, sure, add comments. But why write code that's not clear? > I'm not denying there are occasions where comments add nothing to the > reader's understanding of the code. But they are usually not cases > where the comment repeats (in English or some other natural language) > what is being expressed in Lisp or Java or XSLT or whatever. > Repetition is not in itself bad. On the contrary, it can be explicitly > good, because places where what's written in the comment describes > something different from what's described in the code are probably > places for bugs. It's a bug for sure. The wrong comment should simply be deleted. > I've never, in my life, worked with another programmer who commented > too much. I myself commented too much when I was less experienced. My comments were ridiculous and harmed the understanding of the actual code. > I've once in my life worked with another programmer who > commented enough. In my experience, if you take over someone else's > code either to maintain it or to integrate it or to reuse components > from it, you're normally in for a huge learning process which would > have been obviated simply by adequate commenting. If you don't understand a piece of code, with comments or without comments, you should not touch it. There's a learning curve when you take over a piece of code, comments or no comments, period. > 'Redundant comments are useless' is the mantra of the dilettante, the > amateur, and the cowboy. ... and the true professional. Telling which is which is the job of the hiring manager. I guess if you are the hiring manager, you wouldn't hire me. I'll work for your competitor, where codes are strong, comments are lean, and every one is above average. :) [For the humor impaired, the last sentence is meant to be a joke. A joke is something that is supposed to be funny. Funny things should make you laugh. And laugh is the act where your facial muscles move in a certain way as to effect a configuration of your face where the corner of your mouth rises above the center of your mouth. This paragraph is also an example of over-the-board commenting.] -- Weiqi Gao weiqi...@gmail.com http://www.weiqigao.com/blog/ --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
