[spion]

Yup. Which is why I believe that if you really want to teach someone software design principles, you have to be prepared show them an actual, real software system; the real problem you encountered; the reason why you picked a particular solution; and the results of that choice (both pros and cons). All the details.

Given that data, its easy for a developer to extrapolate (more general) principles that may apply for their own concrete situations and problems, if any.

If you do the extrapolation of the principle yourself but hide the data that caused you to arrive to that principle, nobody will learn anything.

I have no idea why software architects do this. I guess because they're so used to abstracting all the details away in software, they start thinking it also applies to teaching/writing. It does not.

[AnimalMuppet]

I think it's like this: Six months to two years after starting a moderately-sized code base, you start to see why these things are important. You see that they're actually saying something fairly (though not totally) concrete. The more experience you have bumping into the issues, the more concrete the advice becomes.

But I can't give that to you in something that you can read in an hour, or even a day. I might be able to give it to you in something you could read in a month (of 8-hour days reading). It's really hard to show in a one-page example.

[spion]

An essay of 10-100 pages with references to the corresponding code is completely acceptable. The problem is, nobody actually does this while they're learning about it (or rather, they have other more important things to do, like the actual refactor) so there are little or no records of it.

GoF almost managed to do it, except they removed the real system context. One can almost learn something from that book :)