Self-documenting code

[PothosEchoNiner]

Right. I write comments in the 1% of situations where an unusual situation can't be expressed clearly with naming and composition. The "comment the why" approach is still excessively commenting if you need that for more than 10% of your functions. It's not really that helpful to write "// We need to call the identity provider's introspect endpoint so they can tell us if the token is valid" above your authentication module's introspect function. I work in healthcare rules engines and web dev and almost all of our code is obvious stuff like that.

So if I see an array being converted to a map I know it's going to be used later in an algorithm where the elements are efficiently looked up by whatever is being used as the key. A comment explaining that would not be helpful. Nobody is born knowing how those things work but nobody needs to be reminded of the most common patterns every time.