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

81–90 of 181 posts

Re: Useful and useless code comments

#81

Post by nicoburns »

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…

If you use a comment instead of breaking a block of code out into a function, don't you still have one source of truth?

Re: Useful and useless code comments

#82

Post by jeromenerf »

Nimitz14 wrote: post #75

99% of code is internal and something noone unexperienced will look at. If you're writing code for a tutorial for newbies then yeah, it makes sense to add obvious comments. But that's really it. The author is overstating his case.

I have the exact opposite point of view. 99% of the code is written by inexperienced people and passed on to the next generation that of inexperienced developers.

Most development has been, is and will be for the foreseeable future outsourced, not in house. I don’t like that, but I have seen things.

Too much comment about is never a severe problem. At most a distraction.

Re: Useful and useless code comments

#83

Post by cjfd » 

  // Add a vertical scroll bar
  vScrollBar = new JScrollBar(JScrollBar.VERTICAL);
  add(vScrollBar, BorderLayout.EAST);
This actually is helpful if a somewhat long list of components is being added. It makes it easier to find ones way in that list. Kind of like an index. So it really is not a useless comment.

But there actually are useless comments. Like when people are told to explain every class member and one ends up with

DatabaseConnection conn; // connection to the database

This really is just clutter and the next problem is that it needs to be updated alongside the code. I once had a colleague advocating adding a comment for every parameter that a method has and then he would himself not update these if parameters were removed. That really is not very good.

Re: Useful and useless code comments

#84

Post by kwinten »

bipson wrote: post #78
kwinten wrote: post #76

Earlier quoted context omitted.

Careful, you might trigger about half of HN with your proposal of readable code and small functions. This is literally always the right answer. Create a self-explanatory function or just use readable variable names. Or even createScrollbar(Direction.VERTICAL) if you hate repeating yourself.

It triggers half of HN because taken at extreme (abusing) this advice will render code unreadable again. It is never clear cut. But if you never reuse the same code, or it is targeting the wrong abstraction layer (you can't reuse the function without introducing another set of arguments) and you are merely encapsulating two already very readable lines of code, you might end up with a too much redirection and an incre…

If the lines of code were already very readable, they wouldn't require a comment. Comments are for interfaces or complex or inobvious code that can't easily be made more obvious simply through an expression of code IMO.

The code example of the OP is excellent because there are literally so many more avenues for code readability that are all superior to comments. First of all, the same code can literally be reused in the next line:

    addScrollbar(HORIZONTAL);
    addScrollbar(VERTICAL);
Do you frequently or always need to add both scrollbars to the UI? Another chance for reducing repetition and error-proneness when refactoring:

    addScrollbars();
There's no increase in mental load because chances are you'll never need to navigate into these functions to know what they are doing at all, you can read over them as you would normally when you read the "This adds a horizontal scrollbar" comment, and trust that the implementation does what it says on the tin.

Re: Useful and useless code comments

#85

Post by bipson »

I can relate to where the author is coming from.

What these comments do is give the code structure, and giving an outsider a better/faster view into the code, when he has no internal model for the library/framework/API/language which helps him recognize the statements (this outsider might be the author himself, or "future me").

Not knowing what these lines do, I can at first glance (i.e. skimming through the code) understand the author's intentions, what each line is responsible for. This is simply reduction of mental load and I even do this just for myself when trying to wrap my head around a new library or language.

On the other hand, if you are writing for a (large) internal codebase, where you need to find a tradeoff between reduction of mental load and bloat, such comments can quickly become a nuisance...

Then again, the cost of useless comment is usually much smaller than the cost of mental load (everyone knows how to ignore comments, unless they fill pages...)

All this being said, I can only recommend "The Art of Readable Code" - Boswell [1].

[1] https://www.oreilly.com/library/view/the-art-of/978144931848...

Re: Useful and useless code comments

#86

Post by bipson »

kwinten wrote: post #84
bipson wrote: post #78

Earlier quoted context omitted.

It triggers half of HN because taken at extreme (abusing) this advice will render code unreadable again. It is never clear cut. But if you never reuse the same code, or it is targeting the wrong abstraction layer (you can't reuse the function without introducing another set of arguments) and you are merely encapsulating two already very readable lines of code, you might end up with a too much redirection and an incre…

If the lines of code were already very readable, they wouldn't require a comment. Comments are for interfaces or complex or inobvious code that can't easily be made more obvious simply through an expression of code IMO. The code example of the OP is excellent because there are literally so many more avenues for code readability that are all superior to comments. First of all, the same code can literally be reused in…

It seems you did not try to understand my comment:

I said "taken to the extreme". Put differently: If you are going to wrap every pair of lines into separate functions as a way to structure your code, you code will end up becoming functions calling functions calling functions - and whenever you try to read the code, you are required to jump through all these redirections.

Where do you draw the line?

Re: Useful and useless code comments

#87

Post by morbia »

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 scroll bar
  hScrollBar = new JScrollBar(JScrollBar.HORIZTONAL);
  add(hScrollBar, BorderLayout.EAST);
Which suddenly ends up being far worse than having no comment at all. You could say that the second developer should be diligent and ensure they fix these, but given they don't have to change them to meet the requirements you are inviting the possibility that it could happen.

Re: Useful and useless code comments

#88

Post by danuker »

kwinten wrote: post #76
manojlds wrote: post #69

Earlier quoted context omitted.

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

Careful, you might trigger about half of HN with your proposal of readable code and small functions. This is literally always the right answer. Create a self-explanatory function or just use readable variable names. Or even createScrollbar(Direction.VERTICAL) if you hate repeating yourself.

Small functions are all right, but they're a bit more overhead than just a comment (especially if the functionality is used only in one place).

Re: Useful and useless code comments

#89

Post by IneffablePigeon »

tablespoon wrote: post #64
BurningFrog wrote: post #40

Earlier quoted context omitted.

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

I agree with elements of both sides here but I do think there's one important difference with function and variable names, which is that they have to match between definition and usage.

If you refactor a function or variable to do something different, often it becomes obvious at the calling/usage site that something isn't quite right any more and the name gets fixed. Just having more instances of it gives you more opportunities to realise you need to fix the name.

It's absolutely not foolproof, you can obviously still have them get out of sync. I do find it's rarer, though, personally.

Re: Useful and useless code comments

#90

Post by tomerv »

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 never understood this line of reasoning. If you're changing a line of code you should at least look at the whole function that contains it, and update the comments according to the change.

> given they don't have to change them to meet the requirements

What are the requirements? Code review is standard practice, so I see clear code as part of the requirements.

Post reply on HN