Used to work with a guy who would frequently say "a comment is an apology" i.e. the comment is there because the code itself is not clear. That can be the case, but I generally find more comments better than fewer, especially if they relate the code to actual business or functional requirements and don't just restate what the code is doing.

Years ago I would often write comments first. I.e. start with describing the overall goals. Then break it down into routines and order of operations, all still in plain english. Once I was happy with that, I'd break up the comments with blocks of code. I guess this is sort of like "literate programming" though I was doing it long before I ever heard that term and I still have never read much about it. It's almost more like I was prompting myself towards the end goal. The downside of this approach is that the comments do end up more or less just explaining in english what the code is doing, so maybe aren't quite as useful to future maintainers.

I really wish Literate Programming had caught on.

The big problem is folks misunderstood it as documentation (arguably plain.tex should have also been the sourcecode for _The TeXbook_ and that it wasn't is a big part of this) --- it could be, but usually that's better as a separate text/chapter....

I've been trying to collect books on Literate Program/notable Literate Programs published as books:

https://www.goodreads.com/review/list/21394355-william-adams...

and I will note that my own programming took a quantum leap forward when I purchased and read:

https://www.goodreads.com/book/show/39996759-a-philosophy-of...

and applied its principles one chapter at a time to a project which I was able (w/ a bit of help) to get into Literate Programming form:

https://github.com/WillAdams/gcodepreview/blob/main/literati...

There was a phase, which I also got sucked into at the time, that comments are bad. Problem is, to make your code be so self-explanatory that it conveys business decisions, background stories for how you've arrived here, research-based choices made, you would have to name your variables and functions in a batshit_insane_way_that_obfuscates_behavior_among_the_names. It doesn't make anything better.

Use short names where they're contextually clear. Use long names where they're contextually weird/non-belonging. Use comments to explain the "whys" of your code.

I still code this way.