Short version: In a department full of developers, one particular developer’s code can’t be understood by anybody even after multiple hours of descriptions.
It may be my own prejudices, but I’m inclined to think that in the situation described, the code itself is the problem, not the explanation strategy. IMO it’s a common problem with people who are smart and well-educated, but lack the wisdom that comes from long experience, to over-use complex, elaborate architectures and too many design patterns for simple and straightforward projects. The resulting code is usually excessively difficult to understand, prone to obscure bugs, and even more difficult to extend to cover unforeseen edge cases than the simple version would have been.
A few rules of thumb I’ve found useful to avoid the anti-pattern of too many patterns (heh):
Rule of 3. Don’t create an abstraction for a pattern until you have at least 3 examples of it. This helps ensure that it will be used enough times to make sense to be abstracted, and that you actually understand the problem well enough to create a generalized solution. It’s okay to, once you actually have 3+ implementations, decide the cases are not similar enough and/or too far apart to be worth extracting.
Prefer to start with the simple and dumb solution, if needed solving only the simple case of the problem. Push refactoring back until you have it at least sort-of working. Refactor with a focus towards shortening methods and splitting up places that have too many variables in scope when needed.
Bias your decisions towards You Ain’t Gonna Need It. Ideally to the point where you sometimes consciously ignore the full implications of something you are quite sure you really are going to need down the line.
Except that I don’t think that the example of the code that was hard to explain was especially hard to understand? It looked like overkill for the problem, sure, but it didn’t look like it so difficult to follow as to warrant a hours of explanation.
His example wasn’t all that hard, that’s right. But it certainly makes me wonder what sort of things he was doing for larger segments of code.
Please do not post stackexchange questions