Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

My Case Against Code Comments

jakusys.de

Post reply on HN
Print view View original

11–20 of 23 posts

Re: My Case Against Code Comments

#11

Post by Mz »

shaddi wrote: post #8
ekidd wrote: post #4

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:…

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.

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

#12

Post by knieveltech »

dwc wrote: post #10
knieveltech wrote: post #5

Earlier quoted context omitted.

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.

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.

I don't think anyone is advocating for comments explaining that $i is a loop index.

Re: My Case Against Code Comments

#13

Post by abecedarius »

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

#14

Post by prodigal_erik »

Mz wrote: post #11
shaddi wrote: post #8

Earlier quoted context omitted.

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.

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. :-/

An asterisk followed by whitespace doesn't begin italics, so you get * word * rather than word.

Re: My Case Against Code Comments

#15

Post by Mz »

prodigal_erik wrote: post #14
Mz wrote: post #11

Earlier quoted context omitted.

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. :-/

An asterisk followed by whitespace doesn't begin italics, so you get * word * rather than word .

Oh. Thank you!

Re: My Case Against Code Comments

#16

Post by GrandMasterBirt »

ekidd wrote: post #4

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:…

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

#17

Post by GrandMasterBirt »

shaddi wrote: post #8
ekidd wrote: post #4

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:…

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.

That says what I wanted in less words. I like it. You probably have good comments.

Re: My Case Against Code Comments

#19

Post by dwc »

knieveltech wrote: post #12
dwc wrote: post #10

Earlier quoted context omitted.

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.

I don't think anyone is advocating for comments explaining that $i is a loop index.

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

#20

Post by Groxx »

ekidd wrote: post #4

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:…

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

Post reply on HN