Long time ago I wrote...

# If you require a comment for this function you should not be updating this code

...followed by a simple 1-line function

Took 5 years but today someone finally called me out on my snark. My defense was "But it's true. Anyone who doesn't understand that on sight shouldn't be updating that code unsupervised."

Can't wait for this person to find the comment "# This next part is pure, 100% security theater but mandatory per policy"

OK, now I'm being lectured on the purpose of comments in code.

Thing is, above a certain level of fluency, all code is self-documenting. Bottom line is that comments are to help people who haven't reached that level of fluency in that language.

But there's a fluency floor below which unsupervised work is an operational risk. Someone who doesn't get that 1-line of basic code and for whom the function name 'tolower' isn't a big enough clue shouldn't be mucking about in code the team uses daily.

@tdotrob
IMO, the most important job of documentation is to document the reasons, learned by hard lessons, for not trying to do this task in different ways. Second most important task is documenting why you had to do this clearly pathological thing, to accommodate bugs/requirements/limitations in libraries/code you don't control. And third, to document all the ins and outs of external API entry points so that future programmers don't break the security protocols on entry points.

@thereal_renaissance_man All good points, but offer that they apply only to practitioners operating above what I called the "fluency floor" earlier. Someone updating a bash script who doesn't know what tr does won't grok the pathological case you mentioned.

I also note you said 'documentation' not 'comments'. If the shop has good doc discipline I link to reqs/specs in a comment. Hopefully they explain the things you mention in greater detail then the code. If not, comments to the rescue.

@tdotrob
IMO, novices shouldn't be working in code unsupervised. But, even on our best days, veterans sometimes fail to exceed the floor. So, agreed, there does need to be some basics, but you should also be able to assume a basic level of fluency.
RE: docs... I advocate putting pertinent doc as close to where it's used as possible. Having an external spec is fine, but as you said, code is its own best documentation - but clarification doc should be in the code to make it self-explanatory.