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

231–238 of 238 posts

Re: On Comments in Code

#231

Post by ghoward »

benrbray wrote: post #197
cush wrote: post #174

Earlier quoted context omitted.

Until the code changes, then the comments are usually worse than nothing

No. Comments are like a parity check. If the comments don't match the code, then you know that either: 1) The comments are correct, but the code is wrong. This is a bug. 2) The comments are wrong, but the code is correct. This is equally a bug. Whoever makes the change has an obligation to describe their changes with a comment. Code with no comments? Could be right, could be wrong, who knows?

I wish I could upvote your comment more, but putting it in my bookmarks will have to do for now.

Re: On Comments in Code

#232

Post by ChrisMarshallNY »

ItsMonkk wrote: post #230
ChrisMarshallNY wrote: post #44

Important topic. Documentation, in general, could use all the help it can get. I wrote up a long piece on this[0]. No one will read it, because it's long. I've found that no one reads anything that is more than about a "7 minute read," these days. Part of my documentation problem, is that I can get too verbose. It's not a good thing. [0] https://littlegreenviper.com/miscellany/leaving-a-legacy/

One of the key things that I believe is that the world has gone to far in the metric direction. Metrics lead to things like fake reviews, teaching to the test, and SEO. The only way to avoid this is to put your trust into people that you believe have good signal to noise ratios. While posting on HN I believe that your posts have good signal to noise ratios, so I will now henceforth go through your post history lookin…

Hey, thanks!

Re: On Comments in Code

#233

Post by bccdee »

patrick451 wrote: post #168
bccdee wrote: post #152

Earlier quoted context omitted.

I think people often lean too far in favour of "self-documenting code," and "what" comments wind up being underused. The idea of self-documenting code is that the documentation is encoded in the function and variable names, more or less. Sure, extraneous comments should usually be avoided, but frankly, sometimes a couple sentences of plain English is just clearer. I'd rather people just tell me what's going on than t…

When your coding standard enforces 80 characters, you end with a single logical statement split across many lines. This quickly approaches un-readability if you fetishize self documenting code. In my opinion, short variable and function names with a comments are often more readable that self documenting behemoths, e.g., double compute_angular_acceleration_in_radians_per_second_per_second(double torque_in_newtons_per_…

It's also substantially easier to update a comment, making it more descriptive, than it is to update a variable name.

Re: On Comments in Code

#234

Post by alerighi »

philosopher1234 wrote: post #86
alerighi wrote: post #48

Earlier quoted context omitted.

If the name of the function and the parameters are clear, documenting the code seems useless. Take this real example: /** * change the temperature set point in use by the thermostat * * @param ctx the thermostat context * @param sp the new set point in 0.1 celsius degrees * @return 0 on success, But we can change around the name of the parameters like this and use proper strict types: /** * change the temperature set…

Why are method names priveleged over comments? They're both text read for human understanding. Why must the full documentation/definition for a function fit into the length of a method? These are silly restrictions, and lead to worse code.

Because what the code does should be obvious without looking at the documentation. Plus editors will autocomplete function names by looking at the name, not at the documentation. Thus using meaningful names can speed up the development.

Re: On Comments in Code

#235

Post by [deleted] »

benrbray wrote: post #197
cush wrote: post #174

Earlier quoted context omitted.

Until the code changes, then the comments are usually worse than nothing

No. Comments are like a parity check. If the comments don't match the code, then you know that either: 1) The comments are correct, but the code is wrong. This is a bug. 2) The comments are wrong, but the code is correct. This is equally a bug. Whoever makes the change has an obligation to describe their changes with a comment. Code with no comments? Could be right, could be wrong, who knows?

[deleted]

Re: On Comments in Code

#236

Post by cush »

benrbray wrote: post #197
cush wrote: post #174

Earlier quoted context omitted.

Until the code changes, then the comments are usually worse than nothing

No. Comments are like a parity check. If the comments don't match the code, then you know that either: 1) The comments are correct, but the code is wrong. This is a bug. 2) The comments are wrong, but the code is correct. This is equally a bug. Whoever makes the change has an obligation to describe their changes with a comment. Code with no comments? Could be right, could be wrong, who knows?

Good luck maintaining that.

Re: On Comments in Code

#237

Post by cush »

AlotOfReading wrote: post #187
cush wrote: post #174

Earlier quoted context omitted.

Until the code changes, then the comments are usually worse than nothing

I've seen this counterpoint brought up many times before, but I'm struggling to think of the last time I experienced it. Is it really a common problem for you?

Yes, the issue isn't that most comments are inaccurate, it's that the inaccurate ones are so costly. When the comment doesn't match the code, it makes you question the code and the intent. 90% of the time, comments are accurate or just redundant (the code is descriptive enough), but that 10% of the time when the comments says A and B is happening, I end up chasing down whoever or digging through changelogs and tickets to find the comment wasn't updated.
Post reply on HN