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

21–30 of 212 posts

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

#21

Post by troupo »

embedding-shape wrote: post #12
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…

> where each line is extracted into its own method Never heard of "that style of programming" before, and I certainly know that Uncle Bob never adviced people to break down their programs so each line has it's own method/function. Are you perhaps mixing this with someone else?

> I certainly know that Uncle Bob never adviced people to break down their programs so each line has it's own method/function

There's a literal link to a literal Uncle Bob post by the literal Uncle Bob from which the code has been taken verbatim.

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

#22

Post by xlii »

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…

Haskell enters the chat

Haskell (and OCaml I suppose two) are outliers though as one is supposed to have a small functions for single case. It's also super easy to find them and haskell-language-server can even suggest which functions you want based on signatures you have.

But in other languages I agree - it's abomination and actually hurt developers with lower working memory (e.g. neuroatypical ones).

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

#23

Post by Scarblac »

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…

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.

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

#24

Post by toxik »

zero_shift wrote: post #6

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 variab…

I'll be honest, this code is easier to read for me without the comments. Also sorting feels like it's going to be slower than having some kind of set structure? You don't need ordering, just collocation of duplicates. If not or if it's a wash, that is also a good thing to comment. Also I'm not sure about the semantics of Go but it seems this mutates the argument AND returns a value, something I consider dangerous.

Otherwise I agree, people have a weird hang up about short variable names. Somehow not a problem in mathematics...

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

#26

Post by Bootvis »

zero_shift wrote: post #6

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 variab…

I agree this is easy enough to follow but I'd like to quibble about something else:

Comments should answer the question why you are not using some kind of hash set and do a single pass over the data and why it's OK to reorder the strings. One could reasonable expect that Dedupe shows first occurrences in order.

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

#28

Post by shevy-java »

I use a lot of comments, for many reasons.

While it leads to more things to read, which thus may take time, I feel that the benefits of using comments far outweighs the negative sides. This is even valid when comments are outdated usually. To me, adjusting and updating comments often was much easier and faster than describing something de-novo.

In the ruby land this is quite problematic because many do not use any comments. The result is a horrible code base. Getting people who wrote that code to use comments is often too late, as they already abandoned ruby in favour of another language, so I never buy the cop-out explanation of "the code is self-explanatory" - not even in ruby it is. Everyone can write horrible code.

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

#29

Post by Scarblac »

croes wrote: post #7

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.

Yes, but there are other ways to make it more understandable (like good names, idiomatic code, units that are neither too long nor too short) that are often preferable, because comments always have a danger of going out of sync with the code.

The "why" is the part of the explanation that can't be deduced from the code.

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

#30

Post by zero_shift »

toxik wrote: post #24
zero_shift wrote: post #6

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 variab…

I'll be honest, this code is easier to read for me without the comments. Also sorting feels like it's going to be slower than having some kind of set structure? You don't need ordering, just collocation of duplicates. If not or if it's a wash, that is also a good thing to comment. Also I'm not sure about the semantics of Go but it seems this mutates the argument AND returns a value, something I consider dangerous. Ot…

There's probably a better example. The point is sometimes the What needs explanation, and finding a better What isn't practical.

I have slightly unorthodox opinions about short variables. I used to hate them. Then I posted a question on one of the PL design forums - it might have been Reddit r/programminglanguages - why is there are history of single letter names for type variables? ie T, U, etc for generics. The answer I got back, was, sometimes you want code to focus on structure rather than identities. That stuck with me, because it helped me understand why so much C code (including Linux) code uses similar naming practices. Names can lie, and sometimes expressing the structure is the absolute critical thing.

Post reply on HN