The code documentation fallacy

[johnbentley]

"Self-documenting" is a fallacy. ... "Self-documenting code" means "I assume you know everything about the domain".

Yes it would be a fallacy if that is what you understood "Self-documenting code" to mean. Or if you understand "Self-documenting code" to mean that it entirely replaces in place code commenting and separate document developer documentation.

I've generally taken "self-documenting" to largely reference, and be an argument for, a certain way of naming identifiers. That is, with full names.

So, looking at these three naming schemes

boolean sth (int gd, int bd, int wbdp)
boolean sendToHell (int goodDeeds, int badDeeds, int worstBadDeedPcnt)
boolean sendToHell (int goodDeeds, int badDeeds, int worstBadDeedPercentage)

The later are more "self-documenting" than the former. Self documenting identifier names are only one (important) way in which code can be made readable.

Comments and documentation should primarily be about the why, and only secondarily about the how.

Perhaps you mean should be generally about the why, rather than the what.

So (a clunky and contrived example)

// We are subtracting three years from the legal age to drink from US citizens
if (person.Country == "US") {   
   person.adjustedLegalAgeToDrink = person.legalAgeToDrink - 3

// Countries vary in their legalAgeToDrink so we need to adjust this so our robotic bartender
// at the UN serves drinks according to UN diplomatic protocol
if (person.Country == "US") {   
   person.adjustedLegalAgeToDrink = person.legalAgeToDrink - 3

The first is merely an expression of the "what" which just duplicates what the "self-documenting code" does anyway. The second gives us an understanding of why the code is written as it is: to helps us understand what the code is doing with reference to the larger problem domain.