(This goes for people targetting beginners and intermediate programmers. At advanced levels… I’m not qualified to talk about those.)
Contents
Teaching
Become a Good Teacher
If you’re producing tutorials or books, if you’re teaching courses on programming, you have to be a teacher. Teachers cater for students who learn in different ways – different forms of input, different ways of approaching the material. Don’t use use the method that suits you or the one you were taught: look to teachers in other fields for inspiration.
Encourage Diversity
Diversity of thought is good. Think Different. You don’t just want students who “think like programmers” – remember when real computer users used a CLI? Nowadays, it’s accepted that you can be a geek *and* use a graphical interface or that using a complex IDE (cough, Cocoa) doesn’t mean that you don’t know anything about ‘real’ programming. People who think outside the box will be an asset in application development; don’t tell them that software development is ‘not for them’; don’t make them feel stupid.
Teach every student as if they’ll work on complex, multi-programmer projects
Don’t teach them as if they only ever need the basics if those basics are dead ends. It’s useful to know how to create an object model from scratch, but in the age of Core Data, most people won’t need to, and the ones that do don’t consult beginner/intermediate materials.. Don’t teach them as if they’ll only work on short projects by themselves so they can live out their ideosynchracies. Assume that they will need good working habits that are sustainable for a long time, and that they will be writing code that third parties need to understand.
Code
Explain Fundamentals
Some of your readers won’t understand what your function really does. Don’t assume that readers know; explain it. 95% of example code I see is opaque. Since there are often two or three different ways of doing something, this can get _really_ confusing very quickly.
Don’t Hide Anything
Suspense is very well in genre fiction; in learning to program not knowing what a sample app will do and what will happen is confusing. Don’t say ‘I’ll show you how to manipulate raster images.’ Say ‘I will show you how to take two image wells and drop images in them and automatically overlay those images in a custom view, and which methods you would use for that. Those methods are placed in a custom NSView subclass associated with the view.’
Write Transparent Code
It’s a teaching tool. Don’t use NSImage *bottom;when you could use NSImage *bottomFromImageWell1;. The confused student that looks at the code wondering where the image came from will not exist in the second example. You don’t have to write your own code like this (though it might help), but when you’re writing code that fledgling programmers will encounter, it helps a lot.
Don’t dazzle
We know you’re brilliant. As least, we assume that you’re competent, and that you know a lot of things we don’t. Don’t show us your brightest, most complex code: this is not the time to shine. Mention there are advanced techniques, and focus on what your students need.
Make Code Reusable
Students will want to build on something that’s already there – which isn’t bad practice – so make sure they can. Don’t use opaque shortcuts that are only valid in a small set of circumstances: you don’t want to teach them _this function_ you want them to learn _how to write *a* function_.
In the same vein, don’t hardcode anything. Don’t use int y; when you are dealing with
for (y=0 ; y<2 ; y++)
for (y=0 ; y< noOfRows ; y++) - define int noOfRows = 2; once and you're done. And your students will thank you for it.
Flag Deviations
Learn this sentence by heart: "This example does not conform to the 'Model View Controller' pattern." That's the single most common problem I see, but not the only one. If you simplify your code to handwave necessary stuff so your students can concentrate on the basics of something (which isn't evil in itself), say so. Alert your students to the fact that what they see is *not* a real-world example, but a teaching function, tell them what the real thing should look like - and if you're putting up example code somewhere, provide Chapter 3 (teaching).xcodeproj as well as Chapter 3 (fully functional).xcodeproj _so they can see the difference_.
(This article will be revised in the future.)