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

71–80 of 181 posts

Re: Useful and useless code comments

#71

Post by wilsonrocks »

nitrogen wrote: post #13
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…

Make it clear, add structure, add visual boundaries. And push back hard against linter/prettifier rules that remove all developer discretion from layout and structure.

I'm all in on prettifying... If it's done automatically. I find it such a good tradeoff to not have to think about it that I'm happy to accept the times when I think my discretion would do it better.

That said, I've started to develop strong views on some eslint rules. Usually around things being errors that should be warnings in development, like logging messages or debugger or unused variables. I like to run in CI with max warnings being zero to catch them then.

Re: Useful and useless code comments

#72

Post by js8 »

perl4ever wrote: post #59
js8 wrote: post #55

Earlier quoted context omitted.

This might be more readable if setting up those things doesn't involve a set of common variables (say a GUI style in this example) that can affect them. If it does, then you have to pass them around (into these functions) and it makes more difficult to figure out, if one of these variables changes, what all is affected by it (you have to look up all those methods). In short, I don't think adding depth to a hierarchy…

>setting up those things doesn't involve a set of common variables So...object methods?

So what with them? I don't see how they solve the problem.

What you seem to suggest is refactor the original code (which presumably was a single function to set everything up) so that variables used and the substeps are in one module (your new object), and the code that uses all of this is in another module. I am not convinced this really follows "high cohesion, low coupling" dogma, since you put together things that might be less related (different style variables) into the same module, and created a function, which almost all it does is calling into another module, and is highly dependent on it.

The problem ultimately is data relationships in the code can be a general graph, and trying to put a general graph into a hierarchical structure (much less one that actually has to follow the structure of operations on the data) always has to break cycles in some way. And how much you can really do it depends on cyclomatic number of the graph, and if it's high, no strategy is going to be good. AFAICT most of the OOP strategies of "dealing" with this problem are just creating more nodes in the graph, making the structure bigger, but not really reducing the cyclomatic number.

Re: Useful and useless code comments

#73

Post by lordnacho »

I think the bar of usefulness for comments should be pretty low. Most modern IDEs will dim them for you anyway, so it's minimal how visually annoying it is.

The problem is more that you might not have a comment when you need one. There's a lot of times when the author has thought a lot about something and thus understands it, but someone glancing over the code might not.

Example:

    def caterpillarMethod(A, s): 
      n = len(A)
      front, total = 0, 0
      for back in xrange(n):
        while (front
Someone reading this might think it's O(n*2), because there's a loop in a loop and that often makes it so. But if you look closely it isn't. So maybe comment that.

Re: Useful and useless code comments

#74

Post by rerx »

rualca wrote: post #68
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…

Then these two lines of code move away from the context of the surrounding function. There may also be something specific about how the scrollbar is added in this instance, requiring a very complicated name if you want to convey that.

As long as the surrounding function is not overly complex, I don't see the advantage of having to jump back and forth from mini function to mini function to understand what the code is doing.

Re: Useful and useless code comments

#75

Post by Nimitz14 »

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.

Re: Useful and useless code comments

#76

Post by kwinten »

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

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.

Re: Useful and useless code comments

#77

Post by rerx »

wyqydsyq wrote: post #48

> I find them useful as I write code because they allow me to state my intention (in plain English), translate it to code, then compare statements and see how well I’ve achieved my goal. IMO this is exactly what unit tests should be used for. Replace these comments with unit tests and you're doing TDD. The practical difference is by stating your intention as unit tests, you not only verify your initial implementation…

If you are not careful, you end up with 1000s of tests that are tightly coupled to your implementation, testing internal details of your systems, not their behavior. They become a massive burden if you decide to refactor a system and change its internal implementation.

Do test-driven development, but consider deleting these internal tests once you have scoped out how your initial implementation should work.

Re: Useful and useless code comments

#78

Post by bipson »

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.

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 increase in mental load.

What I'm trying to say is: It might be even harder for the outsider to follow/read the code, just simpler on first glance.

Re: Useful and useless code comments

#79

Post by mr_mitm »

aspaceman wrote: post #61
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…

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.

> You don't always want to separate out a function,

Why not? The above could have easily contained a `ensureDirectoryExists(item)`. It would have the benefit of being more reusable, too.

Re: Useful and useless code comments

#80

Post by nicoburns »

lordnacho wrote: post #73

I think the bar of usefulness for comments should be pretty low. Most modern IDEs will dim them for you anyway, so it's minimal how visually annoying it is. The problem is more that you might not have a comment when you need one. There's a lot of times when the author has thought a lot about something and thus understands it, but someone glancing over the code might not. Example: def caterpillarMethod(A, s): n = len(…

Yep, and while I can understand what this is doing by going through it line-by-line, at a glance I haven't a clue. What is the high-level purpose of this function? This could be remedied with a few good comments.
Post reply on HN