His first "what" example actually explains "why" clear is called two times. The code perfectly captures the "what".
Maybe comments should explain 'what' (2017)
31–40 of 212 posts
Re: Maybe comments should explain 'what' (2017)
#32I 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...
Re: Maybe comments should explain 'what' (2017)
#33[flagged]
> and that's the tolerance banks allow for settlement delays
This is missing from your comment. While I'd probably be able to pick that up from context, I'd have to hold "this is an assumption I'm making" in my head, and test that assumption against all parts of the codebase I encounter until I become certain: this'd slow me down. I'd recommend including the "why" explicitly.
Re: Maybe comments should explain 'what' (2017)
#34These 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 for…
I think the argument against this kind of top comments is that it makes easier to forget to update them if you change the code it refers to.
A single line comment is easy to parse, read and spot as having to be changed when you patch something.
Re: Maybe comments should explain 'what' (2017)
#35I like to see comments for external information that can't be derived from the code or API documentation.
For example, for some reason padding bytes are allowed in variable length integers (LEB128) for reasons I still do not understand:
// Allow padding bytes that do not affect the value
let expectedBits: UInt8 = (result Re: Maybe comments should explain 'what' (2017)
#36I 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?
This is from page 37 of Clean Code:
> Even a switch statement with only two cases is larger than I'd like a single block or function to be.
In his own words, ( page 34 ):
> [functions] should be small. They should be smaller than that. That is not an assertion I can justify.
He then advocates for functions to be 2-3 lines each.
Re: Maybe comments should explain 'what' (2017)
#37I like antirez' style of comments.
He starts implementing any module or function by first writing the documentation for it and let's it guide both the functionality and structure.
Makes Redis also extremely easy and enjoyable to read.
Random example: https://github.com/redis/redis/blob/unstable/src/aof.c
Re: Maybe comments should explain 'what' (2017)
#38Isn’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.
Sometimes good names etc. don’t help. Think of this
https://en.wikipedia.org/wiki/Fast_inverse_square_root
That definitely needs a what comment.
Re: Maybe comments should explain 'what' (2017)
#39Earlier quoted context omitted.
> 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?
This is from page 37 of Clean Code: > Even a switch statement with only two cases is larger than I'd like a single block or function to be. His advice that follows, to leverage polymorphism to avoid switch statements isn't bad per-se, but his reasoning, that 6 lines is too long, was a reflection of his desire to get every function as short as possible. In his own words, ( page 34 ): > [functions] should be small. The…
> to leverage polymorphism to avoid switch statements [...] was a reflection of his desire to get every function as short as possible.
That's both true, but long way away from "every line should have it's own method", but I guess parent exaggerated for effect and I misunderstood them, I took it literally when I shouldn't.
Re: Maybe comments should explain 'what' (2017)
#40[flagged]
Does the caller of the method need to know the three days? Why? What if you update to FED Now and it changes?
It seems like the caller only needs to know that it’s checking within the window, which is then likely a constant (like SETTLEMENT_WINDOW_DAYS) that gives the context.
If you need to, you can add a comment to the constant linking to whatever documentation defines why three days.