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

1–10 of 212 posts

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

#2

Post by awesan »

I feel like no one serious uses the uncle Bob style of programming anymore (where each line is extracted into its own method). This was a thing for a while but anyone who's tried to fix bugs in a codebase like that knows exactly what this article is talking about. It's a constant frustration of pressing the "go to definition" key over and over, and going back and forth between separate pieces that run in sequence.

I don't know how that book ever got as big as it did, all you have to do is try it to know that it's very annoying and does not help readability at all.

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

#5

Post by ngruhn »

awesan wrote: post #2

I feel like no one serious uses the uncle Bob style of programming anymore (where each line is extracted into its own method). This was a thing for a while but anyone who's tried to fix bugs in a codebase like that knows exactly what this article is talking about. It's a constant frustration of pressing the "go to definition" key over and over, and going back and forth between separate pieces that run in sequence. I…

I know plenty of Java/C# developers who still suffer from this mind virus ;P

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

#6

Post by zero_shift »

Sometimes I want to use comments because I'm doing something vaguely algorithmic, and I know some readers won't follow the code.

I'm trying to think of a good example, maybe something like a pointer window based function (off the top of my head)

(This isn't real code. Don't get hung up on it)

    func DedupeStrings(ss []string) []string {
      if len(ss)
People will quibble, but

- I'm not convinced you could change the variable names without harming clarity. Would a name like uniquesEndIndex really be any clearer? It adds noise to the code and still doesn't satisfy a confused reader

- I don't want to use function calls for documentation, eg putInUniques(). I'm doing it this way because I want it to run really quick.

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

#7

Post by croes »

Isn’t the purpose of comments to make code understandable?

If that needs a why it’s a why-comment.

If it needs a what it’s a what-comment. Especially if clever programming tricks are used. 6 month later you already forgot what the trick is and how it works.

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

#8

Post by jph »

These examples could both be much better IMHO with a top comment block that describes the purpose of the functionality and shows good usage examples. Something like this below, and ideally using runnable doc comments to help keep the comment correctly explaining the code.

Replace symbol placeholders in the input string with translated values. Scan the string for symbol placeholders that use the format "$foo". The format uses a dollar sign, then optional ASCII letter, then optional word characters. Each recognized symbol is replaced with its corresponding value.

Symbols are only replaced if the symbol exists i.e. getSymbol(String) returns non-null, and the symbol has not already been replaced in this invocation.

Example:

  - input = "Hello $name, welcome to $city!"

  - output -> "Hello Alice, welcome to Boston!"
Return the string with symbol placeholders replaced.

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

#9

Post by aquafox »

I'm a data scientist and a lot of my R code are dplyr-chains a la data |> select(features) |> filter(low_quality) |> mutate(feature=...). It just saves time to comment on what those chains do instead of having go through them every time I want to change something.
Post reply on HN