News for hackers. Stuff that matters.
Re:My Case Against Code Comments by ekidd on Saturday December 18, 2010 @07:20PM (#2020679)
I think everybody hates comments like "getFoo: Get the value of Foo", and huge blocks of commented-out code.

However, I _love_ seeing the following types of comments:

1. The high-level overview of how things fit together: This class represents a compiled method at the VM level. It does not contain the actual native code. If native code exists, it is handled using class Blah instead.

2. What should work, but doesn't: You'd think the following two lines of commented-out code would work, but they don't, because libfoo 1.7.1 and earlier has a stupid bug, so we need to do things the hard way.

3. The epic warning: Apple's Component Manager API does not work the way you'd naturally assume. First of all, it constructs a single 'instance' of a class before it initializes the class. Second, the memory reclamation system is really weird... and so on, for a page and a half.

Re:My Case Against Code Comments by shaddi on Saturday December 18, 2010 @08:12PM (#2020761)
Exactly. Code is for expressing how things are done.* Comments are for expressing why.

* Or if you're not into the whole imperative languages bit, what things are done.

Re:My Case Against Code Comments by Mz on Saturday December 18, 2010 @08:51PM (#2020823)
Totally OT: How are you managing to use an asterisk as a footnote indicator and not ending up with the two asterisks invisible and the text in between in italic? I've seen this before and I've tried to replicate it and I can't do it. :-/
Re:My Case Against Code Comments by prodigal_erik on Saturday December 18, 2010 @09:19PM (#2020872)
An asterisk followed by whitespace doesn't begin italics, so you get * word * rather than word.
Re:My Case Against Code Comments by Mz on Saturday December 18, 2010 @09:25PM (#2020882)
Oh. Thank you!
Re:My Case Against Code Comments by GrandMasterBirt on Saturday December 18, 2010 @09:27PM (#2020886)
That says what I wanted in less words. I like it. You probably have good comments.
Re:My Case Against Code Comments by Groxx on Sunday December 19, 2010 @12:24AM (#2021183)
I think this implies that .NET people love them.

http://submain.com/products/ghostdoc.aspx

Write a function like "getFoo" and it generates that as the description. Similar situation example: http://www.youtube.com/watch?v=yPaNRaub8N4#at=40

Re:My Case Against Code Comments by GrandMasterBirt on Saturday December 18, 2010 @09:25PM (#2020883)
I believe thats commenting on what your intentions are behind something unclear (or making something that looks wrong look right because of xyz) vs commenting on something that could easily be solved by better naming/conventions.
Re:My Case Against Code Comments by rgrove on Saturday December 18, 2010 @07:12PM (#2020661)
Summary: "Bad comments are bad. Good comments are good."
Re:My Case Against Code Comments by mmaunder on Saturday December 18, 2010 @07:57PM (#2020730)
Is the "Error establishing a database connection" on your site illustrative of their mischief at work?

[I don't comment unless it's a TODO or a DONT EVER... ]

Re:My Case Against Code Comments by julian37 on Saturday December 18, 2010 @08:00PM (#2020737)
Re:My Case Against Code Comments by abecedarius on Saturday December 18, 2010 @09:12PM (#2020860)
Nobody writes clearer code than Peter Norvig, yet he usually gives everything a line-or-so doc comment -- e.g. http://norvig.com/lispy2.html. That's pretty far from the comments-should-be-rare credo. I like it.

My actual argument for that style sans appeals to authority: http://stackoverflow.com/questions/499890/what-is-your-perso...

Re:My Case Against Code Comments by knieveltech on Sunday December 19, 2010 @12:59AM (#2021223)
Worthy of a standalone post somewhere so I can add it to my bookmarks. :)
Re:My Case Against Code Comments by abecedarius on Monday December 20, 2010 @05:49AM (#2023946)
Thanks -- maybe I'll get to it soon.
Re:My Case Against Code Comments by dwc on Saturday December 18, 2010 @07:14PM (#2020663)
It's nice to see that yet one more person has come to their senses. Not much new in that post, but sometimes that's ok.

The code itself is always the first, best, and final authority on how it works. Comments should add something beyond that, or they should not be there at all. The Thou Shalt Comment mindset is responsible for most bad comments. Ignore it and only comment when it will do the reader a service.

Re:My Case Against Code Comments by knieveltech on Saturday December 18, 2010 @07:25PM (#2020689)
In theory everything you've said is accurate. In practice it's usually really hard (if not impossible) to know exactly who "the reader" will be in six months. Nothing says "prima dona" to me quite like encountering a few thousand lines of someone else's code that they couldn't even be bothered to document the major functions.
Re:My Case Against Code Comments by dwc on Saturday December 18, 2010 @08:42PM (#2020805)
I comment for "me in six months" and that works ok. Not perfect, but ok. Nothing says "unthinking clod" to me like a few thousand lines of code with comments where I'm told that i is a loop index.
Re:My Case Against Code Comments by knieveltech on Saturday December 18, 2010 @09:01PM (#2020845)
I don't think anyone is advocating for comments explaining that $i is a loop index.
Re:My Case Against Code Comments by dwc on Saturday December 18, 2010 @11:30PM (#2021098)
I don't think so either. But that's what comes out of Thou Shalt Comment. And yes, I have seen loop index comments. Haven't you?

I think we'd both agree if we saw a good comment. I just want to focus on the 'good' part rather than the 'comment' part.

Re:My Case Against Code Comments by knieveltech on Sunday December 19, 2010 @12:53AM (#2021212)
Of course I've seen loop index comments, and redundant variable declaration comments, and all manner of bad commenting. Thing is, I'll take a bad comment over blank code any day.

Crap comments warn me ahead of time that I'm dealing with a developer who's either too inexperienced to know how to comment well or too sloppy to do a good job at it and in either case I need to be paying closer attention to their code than I might otherwise.

Re:My Case Against Code Comments by Groxx on Saturday December 18, 2010 @08:40PM (#2020802)
Commented out code: frequently due to lack of version control, in my experience. Or one-off tests that should've been removed, but they forgot.

  /** Class FooBar - The purpose of this class is to do XYZ... */
  public class FooBar { ... }
>This is one of my favorite examples. Almost an entire line of comments wasted

Not if you use a documentation-builder. They frequently result in simple documentation turning into several lines (@param desc \n @param desc, and the like). /* * does xyz * / does not imply it is documenting that class and only that class. It could easily be meant for two or three classes in the same file, as they could be part of a greater whole.

Re:My Case Against Code Comments by bbuffone on Saturday December 18, 2010 @10:26PM (#2020988)
I am currently getting a "Error establishing a database connection" for the page. I hope where ever that happens; there might be a comment in the code explaining why.