Useful and useless code comments • Hacker News Board

Re: Useful and useless code comments

#121

Post by dmurray » Fri, Jun 18, 2021, 11:11 AM UTC

themodelplumber wrote: post #7

gregschlom wrote: post #4

Fully agree with the author here. I write comments that "repeat the code" all the time, and I like to read them in other people's code. It allows the reader to quickly skim through large portions of code without having to fully decode each line. Obviously, I'm not talking about comment like this (which I see all the time): // adds 1 to x x += 1; That is certainly useless, even annoying. But a small comment every 2-3…

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 use, then a comment can explain why.

Re: Useful and useless code comments

#122

Post by dmurray » Fri, Jun 18, 2021, 11:16 AM UTC

LukeShu wrote: post #44

shusaku wrote: post #32

Earlier quoted context omitted.

The name of the function won’t necessarily reveal the algorithm used in the implementation

Yeah. I'd name the function something like `earthDistance` or `sphereDistance`, and then still have the "what" comment saying "haversine distance formula" inside of the function.

Better still, I'd name it earthDistance and have that be a wrapper for another function called haversineDistance.

Then the user has the choice to call earthDistance to get the program's preferred estimate of distance, or haversineDistance if they want to be certain about the implementation. Later, perhaps you add a new distance formula and earthDistance decides which method to use as appropriate.

Re: Useful and useless code comments

#123

Post by tomtomtom777 » Fri, Jun 18, 2021, 11:16 AM UTC

professor_v wrote: post #100

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

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…

I think the most important drawback of the function for used once code is that its definition doesn't really map well to linear files.

There isn't really a proper place to put such function.

In this example, you would like to define add_vertical_scrollbar() right where it is used as this is the proper context where it makes sense to read it. But if you define it where it's used it no longer adds any clarity.

Re: Useful and useless code comments

#124

Post by dmurray » Fri, Jun 18, 2021, 11:19 AM UTC

ninthcat wrote: post #49

bdcravens wrote: post #16

I generally save comments for WTF code, or to put links that document what's going on. I try to abstract things as a lot of folks are mentioning here, but that just pushes things to another place. Eventually someone is going to need to debug that code. Here's a Puppeteer example, where text is being split into nodes to extract based on line breaks: /* https://medium.com/@roxeteer/javascript-one-liner-to-get-elements-…

If you rewrite it so it's no longer a cryptic one-liner, it's probably easier to understand this way without a comment than the other way with one. return this.page.$eval(selector, (node) => Array .from(node.childNodes) .filter((child) => child.nodeType == Node.TEXT_NODE) .map((child) => child.nodeValue) .join('') .replace(/\s+/g, ' ') .trim() );

Hope this refactor was well unit tested, because it looks to do something a lot different from the original code.

Re: Useful and useless code comments

#125

Post by thrwaeasddsaf » Fri, Jun 18, 2021, 11:37 AM UTC

tempodox wrote: post #116

The article makes some fair points. And once you move beyond the explaining-to-yourself stage, there's yet another reason to have such “useless” comments: quick code navigation. Finding the place in the code where X is being done would be perfectly feasible by consciously reading the code, but I want to save that energy. Letting my visual cortex pattern-match on a syntax-highlighted comment that looks a certain way i…

As always, there's a flipside..

I find code with lots of comments and "fluff" to be a drag to read and navigate and generally work with. I would rather have less to scroll to begin with, than have comments help me jump to a specific spot.

For example, I just replaced a well documented pair of functions that compute a checksum. The original implementation was about thirty lines, including comments and empty lines. My implementation uses a denser style and is just a single function with three lines in the body. I also removed a function argument to make the interface both simpler to use and also less general. KISS & YAGNI: if the more general version is ever needed, then it is trivial to add and make the simple version a wrapper for it. Until a real need shows up, I don't want it.

Of course my changes go way beyond comments, but this kind of thing can make an order-of-magnitude difference in code size (as measured in lines). I would rather work with 300 lines than 3000 lines, and the reduced need for jumping/scrolling around lessens the importance of navigation aids. Also, I find that the aids that are there anyways (function names, etc.) become more useful when there's no fluff to render them ineffective.

Re: Useful and useless code comments

#126

Post by dkbrk » Fri, Jun 18, 2021, 11:38 AM UTC

Someone1234 wrote: post #45

When I was doing CS in college, bad commenting was an academic requirement: As in your grade would be worse if you commented appropriately. Over multiple courses including software engineering, comment quality and or correct use of comments was never in the syllabus. But in several courses they wanted to see the code heavily commented, to the point where you were just re-writing the code as a comment and getting a gr…

This obviously varies, but my experience was very different.

I very distinctly recall being told in an introductory programming course:

"Code is written for people, not computers."

That really stuck with me. What that lecturer meant was that first and foremost code must be written to be comprehensible to other people. The particular techniques used, whether commenting, intelligent variable names, extracting sections into functions or using abstractions are just a means to that end.

And layers of abstraction or indirection can easily harm comprehension rather than help. It all comes down to the circumstances. Do whatever is necessary to make it as comprehensible to other people as possible; everything else is secondary.

Re: Useful and useless code comments

#127

Post by wruza » Fri, Jun 18, 2021, 11:39 AM UTC

tempodox wrote: post #116

The article makes some fair points. And once you move beyond the explaining-to-yourself stage, there's yet another reason to have such “useless” comments: quick code navigation. Finding the place in the code where X is being done would be perfectly feasible by consciously reading the code, but I want to save that energy. Letting my visual cortex pattern-match on a syntax-highlighted comment that looks a certain way i…

I wait for the level of technological advancement when we would have headers and subheaders with various styles in our code, optionally visible on a minimap and on a source tree. And half-height empty lines (like paragraph spacing).

Re: Useful and useless code comments

#128

Post by D13Fd » Fri, Jun 18, 2021, 12:04 PM UTC

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…

The second developer updates or deletes the comment. Yes, this is a maintenance burden. The question is whether the burden outweighs the benefit.

Re: Useful and useless code comments

#129

Post by goto11 » Fri, Jun 18, 2021, 12:10 PM UTC

A tangential point is that the syntax coloring configuration in the editor should emphasize comments.

If comments are de-emphasized (e.g. grayed out compared to code) you will get bad comments and comments out of sync with the code.

Re: Useful and useless code comments

#130

Post by incrudible » Fri, Jun 18, 2021, 12:23 PM 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…

> But you cannot expect everyone to have the same proficiency you do. Writing good code, also means writing code that a newbie can at least comprehend.

If you're writing example code or documentation, by all means, add this kind of comment.

Otherwise, if someone can't comprehend these particular two lines without reading the comment, they need to get back to the drawing board. You can't have noisy code like that in production at the off-chance that somebody with zero competence needs to read it. The expected case is that a competent developer needs to find "the thing", which means they need to be able to scan the code quickly without having to read everything twice. That's what you should optimize for.

The DRY principle also applies, this sort of error is not uncommon:

  // Add a vertical scroll bar
  hScrollBar = new JScrollBar(JScrollBar.HORIZONTAL);