I'm glad LLMs will make these conversations obsolete, just like linters did to tab-vs-spaces
Maybe comments should explain 'what' (2017)
81–90 of 212 posts
Re: Maybe comments should explain 'what' (2017)
#82I 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
This is a great practice. I used to do it when writing complex algorithms, I'd do pseudo-code comments to outline functionality, then basically implement the comments line by line.
Now I sometimes use this practice when working with agents, if I need something done just a certain way. It's time consuming, but it produces good results.
Re: Maybe comments should explain 'what' (2017)
#83[flagged]
> That's explaining "what" but also implicitly "why" - because that's how double-entry works and that's the tolerance banks allow for settlement delays. You can't really extract that into a method name without it becoming absurd. That's why I've also started to explicitly decompose constants if possible. Something like `ageAlertThresholdHours = backupIntervalHours + approxBackupDurationHours + wiggleRoomHours`. Sure,…
we tend to talk about type composition, but values too are composed. this suggestion makes the composition clear and, imo, is strictly better that a hardcoded resulting value. even more so if we assign it using some blocks-with-returns feature, if the language has it: we can clarify that the value’s components are not used elsewhere and thus reduce complexity of the namespace. without such feature, I’m not sure complicating the namespace is worth it, and a comment may actually be better.
Re: Maybe comments should explain 'what' (2017)
#84I also find that phrase super misleading. I've been using a different heuristic that seems to work better for me - "comments should add relevant information that is missing." This works against redundant comments but also isn't ambigous about what "why" means. There might be a better one that also takes into account whether the code does something weird or unexpected for the reader (like the duplicate clear call from…
I like this framing, but might add to it: "comments should add relevant information that is missing and which can't easily be added by refactoring the code".
Re: Maybe comments should explain 'what' (2017)
#85Sometimes 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…
Where is the `sorted` array coming from?
Re: Maybe comments should explain 'what' (2017)
#86[dead]
Re: Maybe comments should explain 'what' (2017)
#87I'm glad LLMs will make these conversations obsolete, just like linters did to tab-vs-spaces
Care to elaborate? It's not obvious to me why/how that would happen. In fact, my experience so far tells me that code with tons of "why" comments (and possibly some "what"s as well) makes LLMs less likely to break stuff.
Re: Maybe comments should explain 'what' (2017)
#88Comments should explain everything, but via links. Large comments cause context rot, so keep your comments tight and focused, and provide links to details as needed.
Agreed... IFF you're linking to something immutable (Jira tickets probably qualify in many enterprise scenarios). Otherwise linkrot is at least as big a problem. Meaningful commit messages surfaced in-IDE via git blame can serve a similar purpose.
Re: Maybe comments should explain 'what' (2017)
#89IMO 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(…
As for the comments, I would probably write it like this:
/* Symbol actually exists */
if ((NULL != getSymbol (symbolName)
/* and still to be added */
&& (!alreadyReplaced.contains (symbolName))
{
...
> Technically this performs worse because you lose short-circuiting
Not really, because optimizing compilers are a thing, when this thing is parsed into SSA, there won't be a difference.
Re: Maybe comments should explain 'what' (2017)
#90I 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.)