Useful and useless code comments • Hacker News Board

Re: Useful and useless code comments

#91

Post by Nimitz14 » Fri, Jun 18, 2021, 7:51 AM UTC

jeromenerf wrote: post #82

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.

You know what, I think you're right I should have been more specific.

99% of code that matters is written by experienced people in my opinion. I.e. the OS, the browser, your favourite apps, websites and programming libraries.

Would you agree with that?

Re: Useful and useless code comments

#92

Post by morbia » Fri, Jun 18, 2021, 8:00 AM UTC

tomerv wrote: post #90

morbia wrote: post #87

Earlier quoted context omitted.

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.

Developers and code reviewers make mistakes. If a change involves looking at code numerous trivial comments, the probability that both the developer and the reviewers misses at least one increases.

This is particularly problematic for this sort of issue because it's impossible for a static analysis tool to pick up.

Re: Useful and useless code comments

#93

Post by rflrob » Fri, Jun 18, 2021, 8:02 AM UTC

I find the choice of the phrase “¿Como te llamas?” fascinating as evidence against “don’t do translation word for word in your head. ” Taken literally, “how (como) you (te) are called (llamas)” has no words in common with “what is your name”. The comments in the code would allow someone with a good Spanish vocabulary to actually translate into fluent English.

Re: Useful and useless code comments

#94

Post by TrianguloY » Fri, Jun 18, 2021, 8:06 AM UTC

For me these comments are useful for two reasons:

1) If you know the author of the code (includes yourself) and you know their comments are a good indication of the code, you just read them and move along. No need to understand what they do.

2) If you don't know the author or you know their comments are often out of date (which you can check with git blame but let's ignore that) the comments tells you what the original intention was, and with an already mental model its easier to read code and understand what it's doing, even if it contains mistakes (in the worst case the code will have nothing to do, so it will be like if you had no comment).

Re: Useful and useless code comments

#95

Post by nemetroid » Fri, Jun 18, 2021, 8:14 AM UTC

stickfigure wrote: post #65

mumblemumble wrote: post #15

Earlier quoted context omitted.

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) langu…

Unlike the original, this doesn't retain a reference to the scrollbar object.

Re: Useful and useless code comments

#96

Post by roelschroeven » Fri, Jun 18, 2021, 8:18 AM UTC

manojlds wrote: post #69

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()

What border layout does that function use? Hardcoded BorderLayout.EAST, as in the code it replaces? Now the function is much more specific than the name suggests. We have a function that looks like it could be used in other parts of the code too, yet was only intended to replace one specific piece of code in one specific function. This is my main problem with extracting even small pieces of code into separate functions, especially in languages that don't have nested functions or similar facilities.

When reading the calling function, add_vertical_scrollbar() makes perfect sense. But when you read the code and you encounter add_vertical_scrollbar(), it is not at all clear where it fits in the grand scheme of things. You could of course add a comment "Meant to be called from this-or-that-function", but that kinda defeats the purpose.

We could make the function more general, which is not always as simple as in this case, but then we're doing more than just extracting some code. Or we could call the function add_vertical_scrollbar_east() instead, but that gets unwieldy pretty fast if there are more tunables.

Don't get me wrong, I do see value in extracting code into functions, and I often do exactly that. But in doing so I notice some drawbacks of that approach that IMO are not generally addressed by small-function-advocates.

Re: Useful and useless code comments

#97

Post by uberswe » Fri, Jun 18, 2021, 8:23 AM UTC

I spend a lot of time reviewing code, I currently review every line of code for 16 other developers.

Obvious comments are great for code reviews because it's a validation that what you intended to do is what your code actually does.

From the article, the comment about adding a vertical scroll bar allows me to review the code and to check that it does indeed add a vertical scroll bar and not something else.

Did the developer intend to require password lengths of at least 8 characters? A simple comment would tell me what the developer wanted to do and then I can verify that it was done correctly.

Re: Useful and useless code comments

#98

Post by mt40 » Fri, Jun 18, 2021, 8:24 AM UTC

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…

I do this all the time as well ever since I knew about this technique.

For me, another giant benefit is that I can scan through the function and understand what it does just by reading the comment. The energy saved by those comments can be spent on writing more code :)

Re: Useful and useless code comments

#99

Post by b93rn » Fri, Jun 18, 2021, 8:37 AM UTC

uberswe wrote: post #97

I spend a lot of time reviewing code, I currently review every line of code for 16 other developers. Obvious comments are great for code reviews because it's a validation that what you intended to do is what your code actually does. From the article, the comment about adding a vertical scroll bar allows me to review the code and to check that it does indeed add a vertical scroll bar and not something else. Did the de…

Great, but that's not the reason why obvious comments are bad. They are bad because it's not maintainable. For you this means that the next time a developer refactors the code, you need to check if the comment is still accurate with the refactored intentions. I repeat, this is not maintainable! I love how the book Clean Code described it: "A comment is a failure to express yourself in code." There are situation they are useful, but those are definitely not obvious comments.

Re: Useful and useless code comments

#100

Post by professor_v » Fri, Jun 18, 2021, 8:44 AM UTC

manojlds wrote: post #69

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()

I can't think of a single benefit of a function over a comment for a piece of code that's only used once. The downsides of the function:

- Unless the function is extremely clear like max() or min(), you will have to read the function and jump around the code. I feel people underestimate the cognitive overhead required for this. This gets worse the more arguments are required to pass around. Linear code is much easier to read.

- More lines of code, a comment adds 1 line while a function or method adds at least 4. Also, code that has to be separated over multiple functions is practically always longer than linear code. Doing this to the extreme can have quite an effect.

- Naming issues, it can be hard to think of a good name for a function and it almost never describes it perfectly. Misnaming things leads to bad assumptions and leaky abstractions. Comments have the luxury of potentially conveying more information and are also less important to get right.

If you use a lot of vertical scrollbars then by all means go ahead and abstract it, but I'd generally pick the comment.