"Uncle Bob" is a bad programmer, simple as. Change my mind!
Did he actually ever write anything substantial, other than that book?
Maybe comments should explain 'what' (2017)
61–70 of 212 posts
Re: Maybe comments should explain 'what' (2017)
#62Explain "why not what" is good general advice. My further advice for comments is: even bad comments can be useful (unless they're from LLM output maybe...) therefore when in doubt, write a comment. Write it in your own words. Had to add the last sentence for the circa 2020s developer experience. LLM comments are almost never useful since they're supposed to convey meaningful information to another human coder, anythi…
I strongly disagree. If you're using something like Claude Code to generate the code, it has significant context about the task, which from my experience provides very useful (albeit overly verbose) comments. I sometimes edit/rewrite its comments (as I might with the code itself), but I would never ask it to generate uncommented code.
Re: Maybe comments should explain 'what' (2017)
#63Ignoring the git commit message strawman (those can include "what/why the change", not "what/why the code") and the Uncle Bob strawman, the final code block looks fine. But notice:
// translate will replace all instances; only need to run it once
// Replace all symbols
String replaceAllSymbols() {
Re: Maybe comments should explain 'what' (2017)
#64I think the benefits of either clean code (sepearate methods) and commenting "what" are of different kind:
- clean code one, for me it just reads easier, specific bits of the larger operation are not surrounded with noise coming from other bits like it is in the commenting "what" one. I can focus more on each step, and that can make it easier to spot a bug or to refactor/adjust/extend, as now I'm more like on a given page of Lego set instructions
- the commenting of "what" one - yeah, this obviously makes it quicker (but probably not easier) to see the larger picture. It has benefits, but I believe this helps more hacker/scripter kind of people than programmers
Re: Maybe comments should explain 'what' (2017)
#65IMO the example shows exactly that splitting code in smaller pieces is way better than just commenting it. It makes it easier for dev's brain to parse the code e.g. to understand what code really does , while fattier but commented version makes it harder but tries to replace it with information about original coder's intentions. Which is maybe important too but not as important as code itself. Not to forget that it's…
Splitting example is way too much indirection, but capturing what the code does in the code itself is a preference for me. In any high level language don't know why the middleground wasn't explored:
var hasSymbol = getSymbol(symbolName) != null
var replacementPending = !alreadyReplaced.contains(symbolName)
if(hasSymbol && replacementPending){
alreadyReplaced.add(symbolName);
stringToReplace = stringToReplace.replace("$" + symbolName, translate(symbolName));
}
Re: Maybe comments should explain 'what' (2017)
#66I 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).
It’s because maths are the ultimate abstraction. It’s timeless and corner cases (almost) fully understood. Ok maybe not, but at least relative to whatever JavaScript developers are reinventing for the thousand time.
Re: Maybe comments should explain 'what' (2017)
#67I 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 wonder how hard it would be to build an IDE "lens" extension that would automatically show you a recursively inlined version of the function you're hovering over when feasible and e.g. shorter than 20 lines.
Re: Maybe comments should explain 'what' (2017)
#68I 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 wonder how hard it would be to have an IDE extension that would automatically show you a recursively inlined version of the function you're hovering over when feasible and e.g. shorter than 20 lines.
Re: Maybe comments should explain 'what' (2017)
#69Earlier quoted context omitted.
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 ans…
Back when I programmed in Haskell, I also had a similar question about the extremely terse variable names that pop up everywhere. I'd wonder, why is this "x" and "xs" instead of "item" and "items" or "businessName" and "businessNames" or whatever. Eventually I found this (paraphrased) answer that made it all click:
The specificity or abstractness of a (variable) name relates to the values that it can hold. So when you have a very abstract function whose inputs can be of almost any type, naming those inputs in an overly-specific manner is an exact inverse of the failure of giving an overly generic to name highly constrained parameter.
Examples of correct naming:
func firstWord(s string) string { ... }
func bidShortcodePrefix(businessId string) string { ... }
func firstWord(strWithOptionalSpaces string) string { ... }
func bidShortcodePrefix(s string) string { ... }
Re: Maybe comments should explain 'what' (2017)
#70[flagged]
> The "what" vs "why" distinction breaks down when your code encodes domain knowledge that readers can't infer from context.
Your comment is a poor example because you unwittingly wrote "why" comments, not "what".
// We match them by looking for equal-opposite amounts within a 3-day window because bank transfers appear as two transactions - a debit here and credit elsewhere
> The Uncle Bob approach of extractNameMatchingTransfersWithinSettlementWindow() doesn't actually help - now I need to know what settlement windows are anyway, and I've lost the context of why 3 days.
You are also completely off in here as well, and I think that your comment shows a deeper misunderstanding of the topic. What you tried to frame as "Uncle Bob approach" actually means implementing your domain in a clear and unambiguous way so that both the "what" and the "why" are clear by looking at the code. Naming conventions are one aspect, but the biggest trait is specifying an interface that forces the caller no option other than doing the what's because of the why's.
Without looking too hard into it, whipping out something like this in a few seconds would match the intent
GetMatchingTransfers(TransferAmount, SettlementWindow)