I have come to a "middle ground," when structuring and commenting code.

First, the code needs to be fairly clear, but not "stupid" clear. I have had people tell me not to use idiomatic Swift, because "a JavaScript programmer can't understand it."

In some cases, this may be necessary, but not in mine.

The #1 consumer of my code, is Yours Truly. The wonkiness doesn't bother me, but sometimes, I may not be aware of why I did something (that may not be "idiomatic," at all).

That's why I may write a quick comment, like so:

        showThrobber()
        // The reason for this, is that we need to give the throbber time to show up.
        DispatchQueue.main.asyncAfter(deadline: DispatchTime.now() + DispatchTimeInterval.milliseconds(20)) {

That explains the awkward use of an "asyncAfter()" method.

It was the result of me, wasting a good half hour, trying to figure out why the screen didn't change. I saved future me, a half hour (and also a signpost for "improvements needed").

I write about my approach to documentation, here: https://littlegreenviper.com/miscellany/leaving-a-legacy/