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

61–70 of 181 posts

Re: Useful and useless code comments

#61

Post by aspaceman »

benhoyt wrote: post #22
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…

Yeah, I like the "visual boundaries" way of framing it. A line of whitespace is a visual boundary, of course, but I find the // comment above it acts as a heading. Like a bold heading above a couple of paragraphs of text in a document. I wouldn't add a heading above every paragraph, but I would might above every few paragraphs. In code, this translates to every 5-15 lines of code. Here's some code I wrote recently th…

Yup. I love this style of using code to create a "paragraph" of code with a section heading. You don't always want to separate out a function, but you do want the advantage of "titling" a section of code.

Re: Useful and useless code comments

#62

Post by OJFord »

mumblemumble wrote: post #15
hcarvalhoalves wrote: post #6

IMO, if I feel the need to add comments to explain code blocks like this: > // Add a horizontal scroll bar > hScrollBar = new JScrollBar(scrollBar, HORIZONTAL); > add(hScrollBar, BorderLayout.SOUTH); It's a sign I should be writing code that reads more like: > addHorizontalScrollBar()

Meh. If you're only doing it once, then I'd argue that the main practical difference between // Add a horizontal scroll bar hScrollBar = new JScrollBar(scrollBar, HORIZONTAL); add(hScrollBar, BorderLayout.SOUTH); and (assuming scrollBar is not a local variable) void addHorizontalScrollBar() { hScrollBar = new JScrollBar(scrollBar, HORIZONTAL); add(hScrollBar, BorderLayout.SOUTH); } ... addHorizontalScrollBar(); is wh…

But now you can also easily test it independently of whatever else is there if required, and the 'section heading' comment (now function name) is much less likely to go out of sync with the actual code, or accidentally adopt unrelated GUI setup that should have been in a different 'section'.

Re: Useful and useless code comments

#63

Post by nerdponx »

tharkun__ wrote: post #36
UglyToad wrote: post #14

Earlier quoted context omitted.

I think my problem with this approach and why I lean to favouring the more obvious and verbose comment is, if I'm reading the code it's probably because something is broken (or I need to change something in the area). With the function I think, "is it and if it is what else does it change?". Is that function definition actually doing what it says it is? So now I have to add another stack frame to my mental model, go…

I don't really get why your mental model is bothered more by the function/stack frame than the comment. Whether I read a function name or comment personally that does pre occupy my mind and sets the mental frame for what comes next. If the comment or function name say doX() or //this does X then I expect it to do that but need to be on the lookout for whether it actually does that. With a function though I can easily…

Stepping in and out is an extra step, mentally and physically. It's increased burden on my working memory, which is usually already quite full keeping track of other aspects of the task at hand.

Also it imposes more burden on the author, and possibly could lead to developing the wrong abstraction, which we all know is bad.

Re: Useful and useless code comments

#64

Post by tablespoon »

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…

> My main solution is to use good function and variable names.

The problem with this is that it isn't actually solution. A name can't contain much that's helpful to know about a thing, which should be obvious given how much prose and narrative everyone produces and consumes. The program itself can only tell you what. Names can sometimes hint at intent, but they they're not very good at it (given the incentive for terseness). Comments are good for explaining the "whys" for a thing as well as intent. Those are important things to know when debugging a problem or trying to enhance something.

Comments shouldn't be thought of as the one thing you need to look at to understand some code. You really have to look at a whole constellation of things (comments, implementation, commit history, tribal knowledge) and synthesize them. When you take that approach, even out of date comments can be more useful than no comments.

> I understand what you mean by "function and variable names are comments". We do use them to describe what the code does. Still, they are actually code :)

They're not any more code than comments are. Run an obfuscator and change all names to random strings and everything will still work fine, just like if you ran a program to strip out comments.

Re: Useful and useless code comments

#65

Post by stickfigure »

mumblemumble wrote: post #15
hcarvalhoalves wrote: post #6

IMO, if I feel the need to add comments to explain code blocks like this: > // Add a horizontal scroll bar > hScrollBar = new JScrollBar(scrollBar, HORIZONTAL); > add(hScrollBar, BorderLayout.SOUTH); It's a sign I should be writing code that reads more like: > addHorizontalScrollBar()

Meh. If you're only doing it once, then I'd argue that the main practical difference between // Add a horizontal scroll bar hScrollBar = new JScrollBar(scrollBar, HORIZONTAL); add(hScrollBar, BorderLayout.SOUTH); and (assuming scrollBar is not a local variable) void addHorizontalScrollBar() { hScrollBar = new JScrollBar(scrollBar, HORIZONTAL); add(hScrollBar, BorderLayout.SOUTH); } ... addHorizontalScrollBar(); is wh…

The whole thing should be condensed to:

    add(new JScrollBar(scrollBar, HORIZONTAL), BorderLayout.SOUTH);
It's self-evident and needs no comment or whitespace to "break it up". This is fundamentally a problem with wordy imperative languages.

A lifetime ago when I wrote assembly code I would write a comment like this to explain every subsequent 5-10 lines of opaque incantation. Higher level (especially functional) languages tend to have fewer issues like this.

Re: Useful and useless code comments

#66

Post by ping_pong »

I think it's stupid when people say they don't think code comments are good or necessary. It's a weirdly religious debate and frankly I think having a ton of code comments is great. Some of my closest friends think that all comments are absolutely unnecessary. We didn't work in the same code repos.

I think 2 IDE features would make things easier for everyone:

1) have an option to remove code comments from view if you don't like them

2) tie a code comment to a piece of code and enforce it. If you change that piece of code, you should be forced to update and tied comments, or force to check that the comment is still correct. And have the fact that you approve a comment should be a part of the check in, so people can trace it.

Re: Useful and useless code comments

#67

Post by NicoJuicy »

rectang wrote: post #57
benhoyt wrote: post #22

Earlier quoted context omitted.

Yeah, I like the "visual boundaries" way of framing it. A line of whitespace is a visual boundary, of course, but I find the // comment above it acts as a heading. Like a bold heading above a couple of paragraphs of text in a document. I wouldn't add a heading above every paragraph, but I would might above every few paragraphs. In code, this translates to every 5-15 lines of code. Here's some code I wrote recently th…

I know this style by the name "coding in commented paragraphs". I learned about it from Damian Conway early in my career, and the idea resonated with me so strongly that I immediately adopted it and have used it every since. I especially appreciate how under syntax highlighting the comments provide a visually offset natural language outline or summary of the code.

Aha, i did this. Knowing a name for it makes it official to defend on PR's :p

Re: Useful and useless code comments

#68

Post by rualca »

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…

> Does it look wasteful to say that you’re adding a vertical bar when you have the following line of code?

It is, if the alternative is to just refactor your code to extract a method so that it reads like:

    addVerticalScrollBar();
No comment, cleaner code, smaller functions/methods, everything is easier to read and follow and reason about.

The main problem with your suggestion is that you're wasting precious space to say the same thing twice.

More importantly, your comments adds nothing important or relevant to those reading the code, such as why did you felt the need to add a vertical scrollbars to begin with. That's the sort of thing that's relevant to those reading the code.

Re: Useful and useless code comments

#69

Post by manojlds »

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…

If that line of code is not obvious, why not add a function and do

add_vertical_scrollbar()

Re: Useful and useless code comments

#70

Post by rhdunn »

I quite often use region/endregion comments to group methods of an interface being implemented, especially if a class implements multiple interfaces. The advantage of those is that an IDE/editor can collapse them and it is easier to see hat methods belong to which interfaces.
Post reply on HN