Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Maybe comments should explain 'what' (2017)

hillelwayne.com

Post reply on HN
Print view View original

161–170 of 212 posts

Re: Maybe comments should explain 'what' (2017)

#161

Post by programmertote »

One thing I learned from programming since the early 2000s, there is no such thing as one size fits all advice. You do what is best for future folks--as I like to call the unfortunate folks who would have to maintain the code I wrote--by providing them helpful hints (be it business rules, assumptions related to code/tech) along with as simply and clearly written code as possible (how do I know if my code is simple and easy to understand? Have a junior teammate review my code and have her/him leave comments wherever she has to spend more than 10-15 mins reading an area in the code).

I hope not of a lot of the future folks hate me for leaving them with ample context and clear/dead simple code.

Re: Maybe comments should explain 'what' (2017)

#162

Post by scottlamb »

scottlamb wrote: post #111

This is tangential to the article's point, but that `replace` function is a complete WTF in a way both authors completely ignore. Because it replaces things in the entire string in a loop, it will translate symbols recursively or not depending on ordering. Imagine you have the following dictionary: a=$b b=oops if your input string just has one of these, it will just be translated once as the programmer was probably e…

> The sane thing would be to loop through building the output string, adding the replacement for each symbol as you go.

As follows:

    // SYMBOL_REF should be a class-level static final to avoid recompiling on each call.

    int pos = 0; // input[..pos] has been processed.
    StringBuilder out = new StringBuilder(); // could also guess at length here.
    Matcher m = SYMBOL_REF.matcher(input);
    while (m.find()) {
      String replacement = symbols.get(m.group(1));
      if (replacement == null) {
        continue; // no such symbol; keep literal `$foo`.
      }
      out.append(input, pos, m.start());
      out.append(replacement);
      pos = m.end();
    }
    out.append(input, pos, input.length());
(Apparently there's also now a Matcher.replaceAll one could use, but it's arguably cheating to outsource the loop to a method that probably didn't exist when the Uncle Bob version was written, and it's slightly less efficient in the "no such symbol" case.)

Coding style must serve the purpose of aiding understanding. If you have strong opinions about the coding style of `replace` but those opinions don't lead to recognition that the implementation was incorrect and inefficient, your opinions are bad and you should feel bad. Stop writing garbage books and blog posts!

Re: Maybe comments should explain 'what' (2017)

#163

Post by scoofy »

I feel like a complete weirdo when it comes to comments and variable names. I've never worked professionally as a coder, but I've been working with python and a bit of js for like 15 years now. I strongly believe that variable names should be long, and explain what they are, and that comments should be long, and explain what's happening.

I have no idea why people want to "save time" to write short comments and short variable names. I just CTRL+C, CTRL+V my variable name anyway. They compound on each other, and that ends up adding an unnecessary level of complexity, and the possibility for errors.

When I come back to a piece of complex code after a year or two, I'm very, very happy that I've used a variable name like "three_tuple_of_weight_radius_price" instead of "tuple" or "t".

Re: Maybe comments should explain 'what' (2017)

#164

Post by rasmus-kirk »

scoofy wrote: post #163

I feel like a complete weirdo when it comes to comments and variable names. I've never worked professionally as a coder, but I've been working with python and a bit of js for like 15 years now. I strongly believe that variable names should be long, and explain what they are, and that comments should be long, and explain what's happening. I have no idea why people want to "save time" to write short comments and short…

I think it's a leftover before proper LSP's, if you had to type/paste everything, that would be fairly tedious, but now-a-days everyone uses LSP's with autocomplete that have all the variables in scope.

I do think very long names can hurt readability though so it's still a balancing act, but variables like "t" (often used in Haskell, ugh) is awful in my opinion.

Re: Maybe comments should explain 'what' (2017)

#165

Post by rasmus-kirk »

hamdingers wrote: post #121
Scarblac wrote: post #23

Earlier quoted context omitted.

Turns out writing a book and getting it published with the title "Clean Code" is great marketing. I have had so many discussions about that style where I tried to argue it wasn't actually simpler and the other side just pointed at the book.

> and the other side just pointed at the book One of the most infuriating categories of engineers to work with is the one who's always citing books in code review. It's effectively effort amplification as a defense mechanism, now instead of having a discussion with you I have to go read a book first. No thanks. I do not give a shit that this practice is in a book written by some well respected whoever, if you can't e…

Yeah, and any of these philosophies are always terrible when you take them to their limit. The ideas are always good in principle and built on a nugget of truth, it's when people take it as gospel I have a problem. If they just read the book and drew inspiration for alternative, possibly better, coding styles and could argue their case that's unequivocally good.

Re: Maybe comments should explain 'what' (2017)

#166

Post by rasmus-kirk »

JanNash wrote: post #32
eterm wrote: post #4

I wouldn't take the examples from Bob Martin as gospel, see also: "Don't refactor like Uncle Bob": https://theaxolot.wordpress.com/2024/05/08/dont-refactor-lik...

Thank you! Taking that refactoring advice at face value when I still was quite junior led to me writing an immensely over-abstracted framework that bit me in the butt for years afterwards when trying to debug or add a new feature. Wasn't easy to unlearn...

Thank God you did. I hear of seniors who still do this shit with no real sense of style because they just assume that over-abstracting everything is always the correct thing to do. You're learning, not unlearning!

Re: Maybe comments should explain 'what' (2017)

#168

Post by [deleted] »

scoofy wrote: post #163

I feel like a complete weirdo when it comes to comments and variable names. I've never worked professionally as a coder, but I've been working with python and a bit of js for like 15 years now. I strongly believe that variable names should be long, and explain what they are, and that comments should be long, and explain what's happening. I have no idea why people want to "save time" to write short comments and short…

[deleted]

Re: Maybe comments should explain 'what' (2017)

#169

Post by gavmor »

scoofy wrote: post #163

I feel like a complete weirdo when it comes to comments and variable names. I've never worked professionally as a coder, but I've been working with python and a bit of js for like 15 years now. I strongly believe that variable names should be long, and explain what they are, and that comments should be long, and explain what's happening. I have no idea why people want to "save time" to write short comments and short…

"tuple" is entirely redundant with the types, though.

Re: Maybe comments should explain 'what' (2017)

#170

Post by zahlman »

matt_kantor wrote: post #90
rossant wrote: post #45

I like to use comments extensively, even if it’s just to visually separate blocks of code in my IDE. A bit more spacing simply feels cleaner to me.

Why not use blank lines? (I suspect the answer might be "my code formatter deletes them", which is a damn shame.)

I used to do that (and it's part of why I put a double line between functions and classes). But over time I started to feel like those were the points where I should just refactor. (If the function can't be cleanly cut at those joints, in turn, I take that as a sign that the logic needs to be disentangled first.)
Post reply on HN