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

On Comments in Code

henrikwarne.com

Post reply on HN
Print view View original

51–60 of 238 posts

Re: On Comments in Code

#51

Post by wongarsu »

rrose wrote: post #32
jbay808 wrote: post #26

Earlier quoted context omitted.

What would be your opinion of this comment, though? // Reset the counter for the next run total_count = 0;

it feels like this suggests a design flaw. You should probably be creating a new local `total_count` variable for each run that goes out of scope at the end of the run, rather than reusing the same variable over and over again in different contexts

  // reuse counter for performance, this brings 2% speedup
  total_count = 0;
would be a quite useful why comment, if not creating a new variable each time is intentional

Re: On Comments in Code

#52

Post by ziml77 »

jaywalk wrote: post #9
krylon wrote: post #7

Earlier quoted context omitted.

A comment like "This method opens a separate database connection so as not to mess with the ongoing transaction" or some such would be rather helpful, though.

Within the code I write, I can't think of a scenario where that wouldn't be obvious. But if it is indeed not obvious, then I agree that would be a helpful comment.

What's obvious now might not be obvious later or to another person.

Re: On Comments in Code

#53

Post by truetraveller »

javert wrote: post #12

I have a personal rule: If I need a comment, it goes at the beginning of the function. This neatly groups the comment with the code it applies to. Occasionally I have to make a function "just" for this grouping purpose, but that's fine.

This is a nice rule of thumb. Works great for 90% of use cases. For the other 10%, it's "acceptable". I like it. It also discourages "what" comments, and encourages longer "why" comments. The biggest benefit is: standardization, and no need to think about comments again.

Re: On Comments in Code

#54

Post by aequitas »

jaywalk wrote: post #4
aequitas wrote: post #2

Code is for computers to make them do exactly what you want them to do, comments are for your co-workers (and you) to make them understand what you actually meant to achieve.

Code involves names of methods and variables which can greatly aid in understanding as well. I've always maintained that comments should only be in code to explain something that is not obvious. If you're calling the SaveUser function and passing in a new User object that you had just created, a comment of "Save the new User object" adds nothing but noise.

Most code (and the effects of removing/refactoring it) are not that obvious at first glance. But I agree, if your code is as simple and self documenting as that a comment like that doesn't add anything. But a lot of the intention cannot be expressed in code alone. This is where comments help enormously. It allows me to review the code and compare it to the writers (often me) intent and spot bugs or refactor if needed. Without it a lot of knowledge has to be rediscovered again.

Re: On Comments in Code

#55

Post by aequitas »

dcolkitt wrote: post #37
ElijahLynn wrote: post #3

The author touches on this a bit but I want to state this really simply: Codes needs "why" comments, not "what" comments. The "what" can be done by self-documenting code, _most_ of the time. You still need to write "what" comments sometimes, don't rule it out completely. And you routinely need to write "why" comments, self-documenting code will never provide the context of "why". Write more "why" comments.

I mostly agree with you, but there are certain cases where you’re making weird and non-intuitive performance optimizations and have to explain “the what”.

But still you have to explain why your code is the way it is on top of that. You can always deduct the what from mentally processing the code, but you can't deduct the why, you only guess.

Re: On Comments in Code

#56

Post by CodeMage »

ithronmellon wrote: post #6
ElijahLynn wrote: post #3

The author touches on this a bit but I want to state this really simply: Codes needs "why" comments, not "what" comments. The "what" can be done by self-documenting code, _most_ of the time. You still need to write "what" comments sometimes, don't rule it out completely. And you routinely need to write "why" comments, self-documenting code will never provide the context of "why". Write more "why" comments.

What belongs in comments describing API methods, why belongs everywhere else.

The point on API methods is incredibly important. True, "Why" is the most important kind of comment, but I disagree with the author's critique of the documentation-generating comments and agree with you.

Yes, "what" comments are a source of additional developer effort and of possible inconsistencies between code and comments, but good API documentation is worth writing and maintaining.

No matter how well you name your method and its arguments, if it's part of the public API and you don't include a comprehensive documentation comment, I'll be forced to dig through your source.

Re: On Comments in Code

#57

Post by simonw »

I care much more about revision history than I do about comments. When I'm trying to figure out code I do it in "git blame" mode - what I'm hoping for is a single, atomic commit that links back to an issue thread. Ideally that issue thread will have all of context I need to fully understand the change.

This works great in codebases that are designed to be read in that way, which is why I'm so keen on every commit combining tests, implementation, updated documentation AND a link to the associated issue thread.

I'll sometimes open an issue seconds before I make a commit, just so I can have an issue number I can associate the commit with. This is great for adding commentary later on - I might post a comment on an issue thread a year after the commit that help clarify some useful detail that, with hindsight, I should have recorded.

Re: On Comments in Code

#58

Post by d23 »

The only thing I would add is that header-style comments are immensely helpful for "chunking" the code into distinct sections. I first saw this recommended in Code Complete, and it stuck with me, since I've seen it in a number of other domains. It's a basic part of cognitive psychology that makes information processing and retention much easier.

Re: On Comments in Code

#59

Post by da39a3ee »

I find Rust crate code to be quite difficult to read sometimes because it contains a lot of comments and executable examples destined to be incorporated into auto-published (and auto-executed) documentation. That's a fine thing of course, but it would be nice if there were facilities to see "just the code and code comments".

A somewhat random example is https://github.com/ogham/rust-ansi-term/blob/master/src/styl...

Re: On Comments in Code

#60

Post by dlp211 »

latchkey wrote: post #30
jbay808 wrote: post #26

Earlier quoted context omitted.

What would be your opinion of this comment, though? // Reset the counter for the next run total_count = 0;

why are you resetting the counter?

For the next run. Why is in the comment, it's likely a design flaw though and no comment is going to help here. See comment about using proper scoping.
Post reply on HN