The following came to mind a while ago in regard to aspiring programmers who visit forums such as this.

The Magpie's Nest
By Joseph Jacobs

All the birds of the air came to the magpie and asked her to teach them how to build nests. For the magpie is the cleverest bird of all at building nests. So she put all the birds round her and began to show them how to do it. First of all she took some mud and made a sort of round cake with it.

"Oh, that's how it's done!" said the thrush, and away it flew; and so that's how thrushes build their nests.

Then the magpie took some twigs and arranged them round in the mud.

"Now I know all about it!" said the blackbird, and off it flew; and that's how the blackbirds make their nests to this very day.

Then the magpie put another layer of mud over the twigs.

"Oh, that's quite obvious!" said the wise owl, and away it flew; and owls have never made better nests since.

After this the magpie took some twigs and twined them round the outside.

"The very thing!" said the sparrow, and off he went; so sparrows make rather slovenly nests to this day.

Well, then Madge magpie took some feathers and stuff, and lined the nest very comfortably with it.

"That suits me!" cried the starling, and off it flew; and very comfortable nests have starlings.

So it went on, every bird taking away some knowledge of how to build nests, but none of them waiting to the end.

Meanwhile Madge magpie went on working and working without looking up, till the only bird that remained was the turtle-dove, and that hadn't paid any attention all along, but only kept on saying its silly cry: "Take two, Taffy, take two-o-o-o!"

At last the magpie heard this just as she was putting a twig across, so she said: "One's enough."

But the turtle-dove kept on saying: "Take two, Taffy, take two-o-o-o!"

Then the magpie got angry and said: "One's enough, I tell you!"

Still the turtle-dove cried: "Take two, Taffy, take two-o-o-o!"

At last, and at last, the magpie looked up and saw nobody near her but the silly turtle-dove, and then she got rarely angry and flew away and refused to tell the birds how to build nests again.

And that is why different birds build their nests differently.

And why some programmers remain here to learn from the magpies, and why we see a lot of thrushes and blackbirds pass through -- and perhaps a few notable turtle-doves as well.

---

At my place of employment we are considering developing a "Coding Guidelines" type of thing. Whenever I start attempting one of these, I remember back to when I first read the Indian Hill Style Guide and couldn't imagine who had come up with something so horrible! But now since I agree with most of it, as I attempt to write an initial draft I begin to remember many of the steps I took along the way to slowly and sometimes painfully learn in full all of the good practices that were plainly laid out to me early on.

With a new semester upon us, I've already given my short version of don't use scanf a couple of times. Much of the time it gets followed up by, "Okay, but how do I use scanf ?" And then some blackbird comes along and carries the thrush away.

Oh well, there are those few who learn by reading; some who learn by observation; and the rest of them have to pee on the electric fence for themselves.

Dani AI

Generated

captured the real danger: when teaching is fragmentary, learners copy the visible step and miss the reasoning that makes it correct. That same mistake turns a "coding guidelines" document into a set of fashionable trinkets instead of a tool for steady improvement. Below is a compact, practical blueprint to create a short, usable guide that also teaches the why — so newcomers graduate from mimicry to good judgement.

Start small and focused: define purpose and scope (which languages, project types, and problems it solves). Pick 3–8 high-impact rules to ship first (naming, formatting, error handling, tests); for each rule give a one-line rationale and a single short example showing the problem and the preferred fix. Avoid long lists of absolute bans at launch — rules without context get misapplied.

Make the guide easy to adopt: automate enforcement where possible (formatter, linter, pre-commit hooks, CI checks) and keep the human checks lightweight (a short code-review checklist). Treat the doc like code: keep it in version control, accept edits via pull requests, and require a short rationale for new rules. Roll out rules gradually: pick three that reduce bugs or review friction, measure adoption, then add more.

Culture and exceptions matter: document an exceptions/waiver process, show real examples from your codebase, and pair the written guide with short live sessions or onboarding exercises so different learners (readers, observers, doers) get what they need. Keep the tone educational, not punitive. Thanks to for the parable that sparked this, and to and for the encouragement — the best guides teach the whole job, not just the first tidy trick.

Recommended Answers

All 2 Replies

What a thing to write Mr. Dave!!

Really an interesting read (both the story as well as the quote at the end).

Inspiring!

Be a part of the DaniWeb community

We're a friendly, industry-focused community of developers, IT pros, digital marketers, and technology enthusiasts meeting, networking, learning, and sharing knowledge.