I am newly aware of an old phenomenon. It is the difference between knowing and doing. People know some large body of knowledge, (like C++), and think: “You only have to add three lines there to add that new feature” or “The answer to your question is manifest in these five lines of code which are exactly where they should be.”. People have no visceral concept of how much they need to know in order to see that some change is indeed trivial. That ‘tacit knowledge’ is not only of C++ but the nature of the surrounding code. It may be trivial to do but it is not trivial to come to know how to do. Too much of today’s software support technology is devoted to making it easy to do things and too little is devoted to making understanding easy. IDEs help, after you have learned the IDE.
The preprocessor of C++ is very powerful but it is too much like an extension to the compiler. Reading preprocessor language extension definitions is too much like reading a compiler source code in order to learn to use a language extension.
In short people (myself included) seem to be unable to judge what body of knowledge they use, in order to know what to do.
Don Knuth once noted that he needed 11 manuals open in order to learn the meaning of a particular call site.
In another example “printf("%d = %s\n", j%10, "modulus");” requires several chapters to explain. Those chapters are in the head of any C programmer, but to a casual reader one of whose languages is not C, it is a long slog. In this toy example the chapters can at least be all found in one book.
I think even with close attention to this problem it will remain difficult to dig into alien technologies, but I think it is now at least twice as hard as it needs to be. Little attention is paid to this problem in the design of new platforms. It is a difficult task. I admit that I am incompetent to judge how well we do in this regard with the technology that I push at my site.
Stroustroup’s C++ manual is a gem for it describes why he defined C++ as he did. It is perhaps unprecedented in this respect. It is a tremendous asset for the C++ expert and greatly improves the art of producing C++ programs. Few other languages have such a document — but it is not a reference. There is a chapter titled “Strings” where you might expect to go to learn how to use strings. Instead it illustrates how that vital standard string facility is added using the C++ language extension features introduced in the preceding 600 pages. In this regard it is again like reading the compiler to learn how to express a+b*c. Instead of describing strings it is a marvelous pedagogical tool—to consolidate the contents of much of the previous 600 pages—a worked example of extending the language. It is a grossly inefficient way to learn how to use the resulting string type.