On Fri, 30 Jul 2021 23:31:39 +0200
Arnt Karlsen <arnt@???> wrote:

> On Thu, 29 Jul 2021 20:10:24 -0400, Hendrik wrote in message
>
> > I ofter predocument -- explain what my code is intended to do
> > before I write it.
>
> ...and what a lot of bug hunters would wanna have handy to answer the
> "What the F*** were they even trying to do here???" debugging things.

I like the notion of having a planning document which is then copied
into pseudocode, which is then transformed into comments-and-code.

- The code borrows from the grammar of the pseudocode to keep it
almost-language.

- Terse comments; a simplification of anything that should stay
actual-language.

- Explanation comments.

I think negatively of explanation, and keep the mindset to wonder if
it's because the code itself is unclear, and therefore "bad" (which it
may or may not be).

Those explanations are often justifications: "Not mine", "I was told
this is correct", legacy code, licensed code etc.