Source code and a paean to MSDN

It will surprise nobody to hear that, for me, it's all about the code. Clear requirements statements are a must, crisply-written design specifications are crucial, architecture diagrams can convey lots of information, but when it comes to truly understanding a system, service, or API, I want code.

Sample code, test code, prototype implementation code, patches, snippets: give me code.

So I find myself really surprised that, after all these decades, no major computer system comes close to MSDN when it comes to recognizing the importance of code to students. Microsoft does provide plenty of those other materials, but just wander around for a while in the MSDN library and you'll immediately see what I mean about MSDN and code. For instance, here's a page I pretty much randomly brought up: FindFirstFile. There is plenty of descriptive text, of course, but there, big and clear and right up front is the Examples section.

And Microsoft's examples are, almost always, excellent: they are short and clear, but realistic; they include just enough complexity to show things like error-handling, parameter values, possible gotchas you should be prepared for. And if that example wasn't enough, look just after it:

For another example, see Listing the Files in a Directory.

Heck, their HTML even includes a convenient Javascript "Copy" button which nicely copies all the source code into your system clipboard to paste into your editor.

Furthermore, there's just no substitution for source code for understanding complex examples. Try this: Enter overlapped into the MSDN search box. You'll find yourself guided to Synchronization and Overlapped Input and Output, which is a fine page by itself, but (gasp!) no source code! Yet fear not, for the MSDN tech writers know what they are doing; within another click or two you'll be checking out GetOverlappedResult, and what does it say under the Examples section? That's right, "see Testing for the End of a File".

Simple things are simple, complicated things are possible, but, everywhere you go, and everywhere you look, source code. It's what programmers eat, drink, and breathe, and Microsoft is fully aware of that, and gives you lots and lots and lots of code.

So why don't other systems do this? It's been 30 years now, guys! Why is it then when I try the same thing for (say) Linux, and I want to learn how to read all the files in a directory, I can pretty quickly find my way to the Linux opendir API and its manual page, and that of readdir. But where's the source code?

Yes, there are 80 jazillion web sites around that collect this sort of thing, and try to make it available, and if you search for "linux opendir readdir" you'll soon enough find something tolerable, albeit short, poorly-formatted, and cursory.

So please, guys: come into this century, and learn from Microsoft! Your developer documentation is targeted at developers, so show them what they want: source code. When I type

man readdir

in my terminal window, it's great that I get a quick summary of the API and its arguments and return values, and it's nice that you've accumulated some text over the years about some of the complexities of calling the function and dealing with the situations that may arise.

But please, include the Examples! It matters, it really does.

And it's not just operating systems that suffer from these problems. Try learning to program a DBMS in SQL: you know you'll be needing to write a SELECT statement, so let's see what some manual pages look like. Here's one; pages and pages and pages of descriptive text, "railroad"-style syntax diagrams, and, buried down at the bottom, a handful of examples. But here's Microsoft's page; it's short, and what's that down at the bottom of the short and simple page? YES IT'S THE SAMPLE CODE!

Or suppose you want to do some network programming, and you're working in Java, so you look up the Javadoc for the socket object. Groan: text, text, text, and more text. Yes, it's all hyperlinked, but it's just more stupid text! How does Microsoft do here? Well, here it is: yes, there's a lot of text this time (boo on you Microsoft), but there, again, at the bottom: Yay! Example code! Simple, clear, ready to compile and run!

So please, everybody: I know it's hard to admit that Microsoft just has the whole world beat here, but can't all you other folk just get over that, and couldn't you just start putting those examples into the developer docs? Please?

We programmers will thank you. Over and over again.