Earlier quoted context omitted.
Could you provide an example of a function or argument type that needs a 'why' explanation. Not getting it.
Not GP, but here is an example of one: https://git.sr.ht/~delthas/senpai/tree/master/item/ui/buffer... It’s mostly done to mark contentious, complicated, or good enough implementations because after reading the code your first reflex would be: Why is it done that way? Also personally I mark part of the code with short What? or How? comments for quicker scanning especially if the syntax is terse or it’s not immediatel…
I entirely understand the use of why comments in the body of code.
I was more curious about why GP thought that functions and parameters should always have why annotations (and only have why annotations). Which seems a bit monstrous, unless I'm misunderstanding something.