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

Useful and useless code comments

blog.jim-nielsen.com

Post reply on HN
Print view View original

171–180 of 181 posts

Re: Useful and useless code comments

#171

Post by pineconewarrior »

IlliOnato wrote: post #140
pineconewarrior wrote: post #131

Earlier quoted context omitted.

I tried to find more information on this by searching for those terms and "damian conway" but came up empty. Would you mind sharing a link, if you have one?

"Coding in paragraphs" is described in Damian Conway's book "Perl best practices" [1] Myself I like coding in paragraphs very much, and giving the paragraphs one-liner headings (comments) definitely makes code for me more readable and easier to navigate. I usually don't give a heading to a "paragraph" which is just one line, unless that line does something subtle. (Conway provides a definition of "subtle": if you nee…

I code in this way as well, particularly when working with pre-existing, poorly documented codebases

Thanks for the link. I may have to find a copy of that book at the library :)

Re: Useful and useless code comments

#172

Post by mattacular »

emodendroket wrote: post #169
mattacular wrote: post #166

Earlier quoted context omitted.

I guess I have been lucky but I don't really get this. You read comments along with the actual code right? They complement one another. An out of date comment should not ipso facto render code indecipherable and if it does that speaks to a bigger problem with the code itself. I find it strange that people want to throw the baby out with the bathwater when it comes to commenting code just cause they've been bit before…

You don’t see how you could end up wasting time when a comment led to you making an incorrect assumption? If they don’t affect how you read the code would mean they’re useless.

I can see how it could, in theory, if the code is extremely complicated and then the comments are lying to you on top. Again I have never experienced this or anything even close to it in 1.5 decades of coding on teams. Unless every comment is wrong then some of them are useful to someone.

On the other hand, I have been bit plenty of times by incorrect documentation outside of code about libraries and APIs.

Re: Useful and useless code comments

#173

Post by emodendroket »

mattacular wrote: post #172
emodendroket wrote: post #169

Earlier quoted context omitted.

You don’t see how you could end up wasting time when a comment led to you making an incorrect assumption? If they don’t affect how you read the code would mean they’re useless.

I can see how it could, in theory, if the code is extremely complicated and then the comments are lying to you on top. Again I have never experienced this or anything even close to it in 1.5 decades of coding on teams. Unless every comment is wrong then some of them are useful to someone. On the other hand, I have been bit plenty of times by incorrect documentation outside of code about libraries and APIs.

Well, consider that such documentation is often generated from comments.

Re: Useful and useless code comments

#174

Post by IlliOnato »

morbia wrote: post #87
whoisjuan wrote: post #5

I’m on the same page. Just look at the given example. Does it look wasteful to say that you’re adding a vertical bar when you have the following line of code?: // Add a vertical scroll bar vScrollBar = new JScrollBar(JScrollBar.VERTICAL); add(vScrollBar, BorderLayout.EAST); Perhaps. But the comment is making a lot more than simply describing what’s below of it. The comment is doing the following things: - It’s creati…

The problem with this approach comes down to when the functionality of the code changes. Consider the scenario that a second developer has to change your code in the future, for example the decision is made that a vertical scrollbar isn't required anymore and a horizontal one is required instead. It is very possible you end up a comment that completely contradicts what the code is actually doing. // Add a vertical sc…

I disagree that it "ends being far worse than having no comments at all". I think it's still helpful: 1) still provides the visual boundary for the following chunk of code 2) still tells me that the code has something to do with scroll bars

As they say, "Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing" :-)

Yeah, it could trick me, but this is no different to any other types of sloppiness.

Should we stop giving meaningful names to variables and functions, because some developer can change what a function does, or variable represents, but fail to update the names to reflect the fact?

Most of the time when I have to look at the code with out of date comments, after paying some initial "tax" of confusion and lost time, it becomes clear that the comment is out of date(git helps with this, too). So I take time and fix the comment. Or in rare cases when I still don't understand what the comment should say, I put a "FIXME: out of date comment" above the offending line.

One thing I give you: when reading code, I find comments explaining why the code does X, more useful than comments stating the the code does X...

Re: Useful and useless code comments

#175

Post by IlliOnato »

Jetrel wrote: post #111
mattacular wrote: post #50

Earlier quoted context omitted.

This is an often used example in defense of not writing comments but in practice I rarely have encountered an out of date or misleading inline comment. In my experience, everything in code tends to stay up-to-date because it is often written and reviewed by multiple people who have some incentive to keep it correct. It's other documentation outside of code that frequently goes stale.

Having had a lot of experience myself, I sadly can't echo this. A lot of it has to do with stick-and-carrot incentivization, stack ranking, and other stuff. Unfortunately every place I've worked at sort of accidentally pits their programmers against each other in a sort of "who can get it done first" competition, with those who do a quick-and-dirty job getting credit, and those who clean up their proverbial workbench…

I would not agree to work in a place like you describe if they doubled my current salary.

I really hope these companies compensated you well...

Re: Useful and useless code comments

#176

Post by IlliOnato »

BurningFrog wrote: post #24

The big problem with comments is that they need to be maintained. When the code changes, the comments need to change with it. The never, ever happens consistently. So soon you have the "man with two watches" problem. The code says one thing, and the comments say another. You could fix it, and sometimes you spend that time, but inevitably you also stop reading the comments, since they're not reliable. I've never seen…

This is an argument to keep the comments short and to the point (preferably one-liners for code paragraphs, longer for functions themselves), not to skip them altogether. Then both checking them and updating them becomes less of a burden.

I even find "man with two watches"useful. When I see it, I _know_ that something is wrong here, and it's worth checking. Most of the time the comment is found to be "buggy" (and gets updated), but I have found quite a few real bugs in the code this way.

Re: Useful and useless code comments

#177

Post by IlliOnato »

BurningFrog wrote: post #40
tablespoon wrote: post #33

Earlier quoted context omitted.

> The big problem with comments is that they need to be maintained. When the code changes, the comments need to change with it. > So soon you have the "man with two watches" problem. The code says one thing, and the comments say another. You could fix it, and sometimes you spend that time, but inevitably you also stop reading the comments, since they're not reliable. When you think about it, function and variable nam…

My main solution is to use good function and variable names. Including - and I had some resistance to this - breaking out a variable or function solely to give something a name that needs describing. This way you have one source of truth. It can be wrong, but you only update it once, and it never conflicts with itself. I understand what you mean by "function and variable names are comments". We do use them to describ…

Redundancy helps to spot errors. When I see code like

// add vertical scroll bar

addHorizontalScrollBar(...)

I _know_ something is wrong.

Did the comment get out of synch with the code? Or the developer copied-and-pasted the wrong function? Or the function itself is misnamed? I don't know! Let's investigate... and fix whatever happens to be erroneous!

But when I see just

addHorizontalScrollBar(...)

all I know is that a horizontal bar seems to be added (provided the function name reflects its... er... function). I don't know whether it was intended behaviour. If it has not been, nothing indicates this at all.

I've actually caught real bugs this way, multiple times.

Re: Useful and useless code comments

#178

Post by IlliOnato »

dmurray wrote: post #121
themodelplumber wrote: post #7

Earlier quoted context omitted.

It's funny to recall that when I was about 11 years old, 30+ years ago, I would have thanked you profusely for that comment, instantly unraveling the += mystery.

But in hindsight, it wouldn't be a good comment, because that information is misplaced. The perfect time for you to encounter that comment is the first time you ever encounter the += operator, not every time you encounter it. I generally think you shouldn't comment to explain your use of a language feature, even an unusual one. The exception: when there exists an idiomatic alternative which you intentionally didn't u…

... or when the feature is counter-intuitive and actively confusing, like "oct" and "hex" operators in Perl that do opposite of what one not familiar with them would guess.

Even after many years of programming in Perl I found comments like

# FROM hex, not TO hex!

useful.

Re: Useful and useless code comments

#179

Post by mattacular »

emodendroket wrote: post #173
mattacular wrote: post #172

Earlier quoted context omitted.

I can see how it could, in theory, if the code is extremely complicated and then the comments are lying to you on top. Again I have never experienced this or anything even close to it in 1.5 decades of coding on teams. Unless every comment is wrong then some of them are useful to someone. On the other hand, I have been bit plenty of times by incorrect documentation outside of code about libraries and APIs.

Well, consider that such documentation is often generated from comments.

Fair enough. I will say my recommendation is for writing useful inline comments ("the why" comments and more rarely "the what").

File-level and function-header type comments that tend to generate docs (eg. Doxygen) are certainly more likely to fall out of date (easy to miss in a PR diff etc) and I don't really support using them anyway.

Re: Useful and useless code comments

#180

Post by ilyash »

whoisjuan wrote: post #5

I’m on the same page. Just look at the given example. Does it look wasteful to say that you’re adding a vertical bar when you have the following line of code?: // Add a vertical scroll bar vScrollBar = new JScrollBar(JScrollBar.VERTICAL); add(vScrollBar, BorderLayout.EAST); Perhaps. But the comment is making a lot more than simply describing what’s below of it. The comment is doing the following things: - It’s creati…

> visual boundary

I agree with this so much that I have added (some time ago) a syntax for that to Next Generation Shell.

https://ilya-sher.org/2019/10/21/section-syntax-next-generat...

TL;DR:

    section "Add a vertical scroll bar" {
        ...
    }
Post reply on HN