On Programming Examples

If there’s a failure common to many programming sites, it’s the lack of useful examples. This goes both for those high level overview examples you see at the beginning of a chapter and for the actual code samples provided a few pages later. This is a problem for me, since I need context in order to really learn something. Neither seeing a block of code with no explanation of what it’s supposed to be used for in a real system nor reading a superficial example of functionality so simple it does effectively nothing stick with me. I see these examples falling into one of two categories.

The first attempts to turn every programming lesson, no matter how complicated, into a “Hello, World!” example. Need to read from an XML file? Great! Here’s how to load a file with one node, choose the one node that’s already there and read from it! Fun! What you won’t learn is how to use actual XML files where there are lots of elements with a crazy mix of child nodes, inner text and attributes. Want to find out how to read specific information from an XML file based on some kind of criteria? Sorry, no, because all we’re going to give you for an example is:

<Library>
  <Books>
    <Book>
      <Title>The Client</Title>
      <Author>John Grishom</Author>
    </Book>
  </Books>
</Library>

When most XML files look more like this:

<Library Name="Moon Public Library" ZipCode="15108">
  <Books Status="Available">
    <Book Author="John Grisham" DateReceived="3/18/2008">The Client</Book>
    <Book Author="Dan Brown" DateReceived="3/17/2008">Angels and Demons</Book>
  </Books>
  <Books Status="Checked Out">
    <Book Author="Guy Gabriel Kay" DateCheckedOut="3/10/2008">The Summer Tree</Book>
    <Book Author="Michael Crichton" DateCheckedOut="3/12/2008">Jruassic Park</Book>
  </Books>
</Library>

Only they look worse and are even less logical.

The second category try to help you understand the theory behind something by providing a fatuous real world analogy. You know, like, how the best way to describe object oriented programming is to compare a class to a blueprint and an object to the car you make with the blueprint, or to say that you can make a car class, and that a Honda inherits the attributes of a car but adds its own things, like comfy seats and an iPod connector, but you can also have a Pinto inherit from a car as well, but add completely different features, such as ExplodesOnImpact. Which would all be great if I, or anyone reading an entry level programming book, was planning on programming a computer to build cars of every make and model.

Might I suggest that if you require a description of object oriented programming that eschews any reference to things you might actually do on a computer this might be too early to study the topic? I’m not saying you need to have three years of experience here. Just that you might want to stick to programming concepts that you can understand in terms of things you might do with a programming language. Let’s try my own example:

You’re writing Pac-Man, but you want to make it Object Oriented because everything must be designed using this paradigm to be correct. Now, you want 4 ghosts, but you want them to all behave slightly differently. You want Blinky to directly attack Pac-Man, and you want Clyde to always try and cut him off. You could code each ghost separately, but there would be a lot of repeated code. They all basically navigate the maze in the same way, and none of them should be able to eat power-pellets, but they should all kill Pac-Man. So you could make a Ghost class that has the generic behaviors, like movement and speed and all that jazz. Then you can make, say, a Blinky class that inherits the Ghost class, but adds an Attack method that figures out the shortest distance between it and Pac-Man. Instant inheritance!

What most examples lack is good context. What’s that Library example supposed to apply to? Are most people looking for examples on XML because they are in a position to create idealistically clean XML, or are they trying to figure out how to parse the monstrous crap pile that their server at work is dumping on them? You may have shown me what the basic structure of XML is with the example, but not any idea of how I’m supposed to use it. Your example is so much simpler than anything I’ll actually encounter that I can’t apply your example to the real world. And the car analogy? Please, bury it somewhere in the middle of the woods. No one reading it is going to get one of those exclamation points appearing over their head from the sudden shock of understanding you’ve delivered to them.

We program in order to accomplish some task. If you want to teach something, put your example in the context of an actual task so that when I go back to my actual job I can actually frakking apply it.

This entry was posted in Coding. Bookmark the permalink.

Leave a Reply

Your email address will not be published. Required fields are marked *