Express routes are defined using functions on the server object that correspond to the HTTP verbs - get, post, del and so on. We can use the functional capabilities of JavaScript to wrap these functions with versions that take an additional, initial parameter, a string documenting the use of that route. Here’s a version which adds the function-wrapping function as a method of the server instance, and encapsulates the data which we’ll use to render a documentation page inthe server object itself:

If you’re not familiar with the JavaScript idioms used here, some points to note:

• oldRouteMethod is declared before, but used inside the anonymous function. JavaScripts lexical scoping means that it’s value will be the object representing the original express route method (get, post etc) wrapped by the new function
• The pattern used by express to define the route can be a string or a regular expression object, hence the toString() call before it’s used as a key into the object holding the documentation strings
• When the old route method is called, it’s passed all but the first argument to the new function. Express lets you provide any number of filters before the function that actually implements the route, so we take the arguments object and slice it by calling Array’s slice method (defined in the Array prototype), but with the arguments object as the first parameter, which makes it the this object inside the call to slice.

Calling the method to replace the existing route methods is simple:

And documenting the methods themselves is subsequently straightforward:

It’s then a simple matter to provide a template to render the routes in an html page, and add a route (documented, of course) to view the page:

Our app developers can now see at a glance on the server they’re using for development which routes are available, their URL patterns and parameters.

After all, recent research shows that people who don’t cite their references go on to have incredibly disappointing sex lives.*

* I made that up. But at least I’m telling you that I made it up.

His charitable trust was sponsoring and promoting the concert, but here he was, patiently waiting in the (slow) queue to speak to Jonathan in the green room. We talked about the concert, and the inspiring musicianship we’d all experienced. It took my suggestion, followed by some persuasion from his minder, for him to jump the queue to congratulate the artist and stand for the inevitable photographs — he was quite prepared to wait uncomfortably with us all on the narrow backstage stairs.

This is what improv teacher Tom Salinsky calls “happy high status” — the ability to raise the status of those around you without diminishing your own. Heaven knows, there are plenty of assholes in all fields of music, but it seems to me that many of the truly great are at ease with their status and don’t feel the constant need to prove to themselves and others that they’re the top honcho, instead sharing their status and making everybody around them feel good. It’s a lesson in modest greatness that many in the increasingly shrill world of lean/agile software would do well to learn

I come back to this piece regularly — one of the first three studies is pretty much always in my warm-up routine when I practice. Here’s how I dealt with the first four bars, with a fingering I settled on when I first learned the piece as a teenager:

This is fine - reasonably efficient and consistent, and certainly playable. But recently I’ve wanted to make more of the harmony — this fingering is too much concerned with one note following the next. This is what I’m currently working on:

Less movement along the strings, more opportunity to sustain the notes of the chords against each other (especially the important lowest part), at the cost of increased variety, and hence complexity, for the right hand.

It’s taken me a week of slow practice (and OK, I’m no longer putting in 4+ hours a day…) for this to feel fluent — there’s thirty-five years of muscle memory to undo — but the result is worth it. For me, changing one’s mind like this is one of the great pleasures of playing music. When was the last time you changed the habit of a lifetime?

Rereading it now, I’m just as impressed — by its vision, its prescience, and its humanity. The prime motivation is Piaget’s thinking on learning — especially the intense, incredible learning that children undertake on their own in the first few years of their lives. It tackles head-on all the current concerns about dissociation between science and humanities, math phobia. A central concept is the idea of an “object-to-think-with” — that can be identified with, that serves as an extension of the self, and that through it’s affordances and capabilities stimulates the kind of purposeful exploration that characterises powerful learning at any ages, especially the early years. Papert tells his own story about one such object, in the book’s preface, The Gears of my Childhood; I like the story so much I’ll quote it at length:

BEFORE I WAS two years old I had developed an intense involve-ment with automobiles. The names of car parts made up a very substantial portion of my vocabulary: I was particularly proud of knowing about the parts of the transmission system, the gearbox, and most especially the differential. It was, of course, many years later before I understood how gears work; but once I did, playing with gears became a favorite pastime. I loved rotating circular ob-jects against one another in gearlike motions and, naturally, my first “erector set” project was a crude gear system.

I became adept at turning wheels in my head and at making chains of cause and effect: “This one turns this way so that must turn that way so …” I found particular pleasure in such systems as the differential gear, which does not follow a simple linear chain of causality since the motion in the transmission shaft can be distributed in many different ways to the two wheels depending on what resistance they encounter. I remember quite vividly my excitement at discovering that a system could be lawful and completely comprehensible without being rigidly deterministic.

I believe that working with differentials did more for my mathematical development than anything I was taught in elementary school. Gears, serving as models, carried many otherwise abstract ideas into my head. I clearly remember two examples from school math. I saw multiplication tables as gears, and my first brush with equations in two variables (e.g., 3x + 4y - 10) immediately evoked the differential. By the time I had made a mental gear model of the relation between x and y, figuring how many teeth each gear needed, the equation had become a comfortable friend.

Many years later when I read Piaget this incident served me as a model for his notion of assimilation, except I was immediately struck by the fact that his discussion does not do full justice to his own idea. He talks almost entirely about cognitive aspects of assimilation. But there is also an affective component. Assimilating equations to gears certainly is a powerful way to bring old knowledge to bear on a new object. But it does more as well. I am sure that such assimilations helped to endow mathematics, for me, with a positive affective tone that can be traced back to my infantile experiences with cars.

Embodying learning in an object-to-think-with to which one develops an affective relationship is a powerful stimulus to owning the knowledge that’s being gained. Papert gives the example from a class using Logo to generate poetry — not what you’d usually associate the language with, but this was a slightly older class. They’d had some ineffective drilling in English grammar some time before, which their teacher hadn’t been able to motivate. But when faced with having to generate sentences, suddenly the previously dry rules and constraints made sense — they had an owned, immediate purpose. Children learn more, and more effectively, about math, coordinates and geometry by programming pictures, sprites and collision detection than by doing sums and exercises”

Arithmetic is a bad introductory domain for learning heuristic thinking. Turtle geometry is an excellent one. By its qualities of ego and body syntonicity, the act of learning to make the Turtle draw gives the child a model of learning that is very much different from the dissociated one a fifth-grade boy, Bill, described as the way to learn multiplication tables in school: “You learn stuff like that by making your mind a blank and saying it over and over until you know it.”

Musicians, I think, never lose this sense of an affective, thought-inspiring object: I’ve found the best are always challenged by the relationship with their instruments, and with the nature of musical sound itself. There’s always more to explore, to learn, and though work away from an instrument has its place, for me it’s always secondary to where sound and the physicality of playing lead me.

There’s lots more to the book, of course. The good news (for me, and I hope for you too) is that it’s still in print, and also available as a download from the ACM. If you’re at all involved in computers and education, or if you need inspiring about the potential for this thing called programming to change the way we live and learn, then you owe it to yourself to read Mindstorms. It’s reminded me of the happy fact that, essentially, I’m paid large amounts of money every day — essentially — to learn and to play.

With some 30 others I was delighted to be part of the Educating Programmers summit, organised by Jason Gorman and held at Bletchley Park last week. The very next day (it really couldn’t have been timed better) Eric Schmidt, in the McTaggart lecture at the Edinburgh Festival, generated significantly more awareness of the woeful state of computing education in this country:

You need to start at the beginning with education. We need to re-ignite children’s passion for science, engineering and maths … I was flabbergasted to learn that today computer science isn’t even taught as standard in UK schools. Your IT curriculum focuses on teaching how to use software, but gives no insight into how it’s made.

(Full text here.)

It was well reported in The Guardian — under the headline Eric Schmidt, chairman of Google, condemns British education system, James Roberson wrote

The chairman of Google has delivered a devastating critique of the UK’s education system and said the country had failed to capitalise on its record of innovation in science and engineering.

The day at Bletchley Park was stimulating, and full of discoveries. Highlights for me, along with links, were

1. Discovering that the irrepressible Simon Peyton-Jones and many others have been spearheading an initiative, Computing at Schools, since 2009. Now supported by Microsoft, Google, Intel, the National Science Learning Centre and the BCS, it’s turning into a serious force giving teachers and technologists a chance to exert influence on policy at a national level, which Jason’s initiative (to provide pracitioner-mentors for teachers in schools, to teach, encourage and inspire teachers) nicely complements.

Check out Computing At School, and the the group’s curriculum proposal submitted to the National Curriculum Review,

Simon also highlighted the Livingstone/Hope report:

…if the UK is to retain its global strengths in the high-tech creative and digital industries more generally it must urgently address the need for more rigorous teaching of computing in schools

So perhaps things will start changing. Simon pointed out that the door to change isn’t closed, but it’s made of lead, and needs a lot of pushing. We hope that CAS, the NESTA report, and the report due later this year from the Royal Society on teaching computing will generate enough momentum at the top to make space for the multiple efforts that will no doubt be needed in the classrooms and teacher training institutions

2. Hearing about what’s possible at the earliest stages of education - inspiring primary school IT coordinator Ian Addison demonstrating some of the work of his classes, using some of the many introductory development environments around.

3. Seeing Eben Upton show and talk about Raspberry Pi — a capable computer built from the outset so that children can get their hands on something they can program, for the price of a text book ($25). I’m really looking forward to getting my hands on one when they’re released, all being well later in the year.

All this took me back to the days of Logo, and reading Seymour Papert’s 1980 book Mindstorms: Children, Computers and Powerful Ideas This made a big impression on me back in the late 80s (when my children were young, and I was teaching them Logo!) More on Mindstorms after a short break…

However, by Sunday afternoon, there was more to be worried about. Namely a blot, growing from the lower corner of my right eye. This happened quite quickly — over the space of some thirty minutes. The obstruction bobbled a little, like a wave or black tide trying to creep over a beach. The penny dropped — I thought that this was what a detached retina should feel like. Two minutes on wikipedia confirmed it, and thoughts of the doctor the next day were replaced by — how do I get to Moorfields as quickly as possible. (Moorfields Eye Hospital is London’s specialist centre for eye conditions, and one of, if not the, leading institution of its kind worldwide).

It turned out that both eyes were affected - left, a small tear at the bottom of the eye; right, several tears and a larger detachment that had spread to encompass the macula - the part of the retina that deals with the centre of vision. We were lucky — a kind neighbour dropped everything and drove us to Moorfields, where we were lucky to hit a quiet hour or two in casualty. Examinations of various sorts confirmed the problem: after an hour or so it became clear that it wouldn’t be possible o have it treated immediately, so arrangements were made (via a doctor who was scarily like Stephen Mangan in Green Wing — hi, Zoltan!) to return the next day. Go home, go to bed, sleep on your right side…

So what is retinal detachment? Think back to your school biology classes: the eye is full of jelly — the vitreous humour — not liquid. (Such an evocative term. I remember being fascinated and puzzled by it at school. Humour? Why humour? What’s funny about it?) Though detachment can happen in a number of ways, in my case the vitreous shrank a little, pulling at the retina and tearing it. Think pulling blu-tack of a wall, and taking the paint or wallpaper with it. Liquid accumulates beneath these tears, separating the retina from the back of the eye. If not treated, it can deteriorate suddenly, and once completely detached, say goodbye to the sight of the affected eye.

Overnight gravity did its work, but it didn’t take long for the blot to return. It was an early start — we’d arrived at the clinic at Moorfields for 7.30, and reassuringly the first person we saw was the surgeon, on whose list I’d been placed for an operation later that day. Most of the day was then spent waiting — lying on the aforementioned right side, whiling the time by listening to music. Both eyes needed work, but the tear in the left would be dealt with by laser from the outside of the eye, with the serious business reserved for the right. Given both eyes would be operated on, I was offered as a matter of routine a general anaesthetic, but chose local. Partly because I really don’t like the woozy experience of waking from GA, but largely because I was interested in the operation, and didn’t want to miss anything. (You’ll have gathered I’m not squeamish… Well, maybe I am, but curiosity has always been a stronger impulse for me than discomfort). Late in the afternoon, the call came, I was togged up in the surgical gowns, and went to meet the anaesthetist.

WARNING at this point, if you’re nervous about needles, eyes, needles in eyes, it might be best to stop reading now…

The eyes were dealt with differently. The left, a quick jab on the inside of the lower eyelid, the right a more complex process. No needles, but a small cut in the membranes, beneath which a local anaesthetic was introduced. This spreads around the eye (all the touch and pain receptors in the eye are one the surface, so this is a very efficient way of putting the eye - and surrounding muscles, as it happens - to sleep). So far so good.

Then into the theatre. If you’re used to medical dramas on TV - well, this one was a lot smaller. Octagonal, with lots of light - in panels, where the ceiling and wall join. By this point, I wasn’t really able to take a good look around… and shortly thereafter more covering around the eye hid the rest from view. It struck me that the surgeon spent a great deal of time getting me, and himself, in exactly the right position - his chair, the angle end height of the trolley, my head just so. The theatre lights were dimmed, and work started on the easy part of the procedure - fixing the left eye tear with laser pulses.

This turned out to be the least comfortable part of the procedure, even though the tear was relatively minor. I was aware of flashes and streaks of red, which sometimes flared up as a bright green/white. After a while my eye ached, and the temptation to blink and turn the eye away was overwhelming, though the muscle had been immobilised. But after five minutes it was over, and the real fun could begin.

The procedure is called Pars Plana Vitrectomy with Gas. You’ll already have worked out this involves removing the vitreous, not by suction (that would pull the retina with it, and somewhat defeat the object) but with a little device that chomps or nibbles its way through the vitreous humour. Occasionally I would catch the shadow of the tip of the tool, and think of Arthur C Clarke’s Von Neumann machines, the sentinel consuming the gas of Jupiter … I digress! With the gel gone, the next step is to tack the retina to the back of the eyeball, either with laser again or (in my case) a cryo probe. Cue much hissing of liquid nitrous oxide, and again, as the procedure continued, some slight, dull pain at the back of the eye. Finally, a little fluid is reintroduced into the eyeball, and a quantity of gas, then stitches in the small openings made for the microsurgery.

All the while the surgeon spoke to his team, and to me, and I asked questions from time to time (hence my new-found expertise in the Pars Plana Vitrectomy). Some things made a particular impression:

a “timeout” at the start of the procedure where the surgeon spoke to the team about what he was going to do;

the fact that most communication was the surgeon asking, telling, requesting. This generated an edge, an urgency to proceedings, which after a while I found reassuring — it kept people focussed;

apart from the surgeon and anaesthetist, the team was not exactly a team (I got the impression that as a group they had not worked together before, though pairs and threes will have spent theatre time together), but more of a crew — roles, activities and procedures so well understood that strangers — with enough in common of shared practice and culture — could come together to contribute to a critical process;

the way he kept calling me “sir” (I asked him about this - he said that it’s not impoliteness, but the fact that when you’re thinking about the three or four things you’re doing inside a patient’s eye, its easier than trying to remember their name);

the bleeping of the blood monitor (what the team listen for mostly is the pitch, which indicates blood oxygen levels: the pulse reading is more or less a byproduct. I’m sure I’m not the only patient who found it useful as feedback, though);

the fact that at one point he reminded the team that they’d all been trained not to trust the surgeon, and to ask or call out if anything wasn’t clear to them, or seemed unusual or incorrect;

the way he asked a trainee theatre nurse to get involved in the suturing — straight out of Gawande!

It all passed very quickly — around an hour in the theatre — and surprisingly painlessly. I’ve had less comfortable visits to the dentist. I was wheeled back to my room, where for the next couple of hours I had to keep my head down: looking at the floor, so that the gas bubble in the eye rested over the repaired part of the retina, its buoyancy keeping the retina firmly pressed against the eyeball. In some cases, post-op recovery involves “posturing” — lying in the same position for several days, to keep the bubble in place. I was lucky: the tear was at the top of my eye, so normal upright posture would be just fine, though to help healing I would have to sleep on my left side for the next week or so. After the operation my eye was sore — gritty and itchy rather than out-and-out painful, somewhat like conjunctivitis. Eyedrops (antibiotic and anti-inflammatory — for a month) brought that under control in four or five days.

And slowly, vision returned. At first, you’re looking through the gas: there’s a small pool of liquid at the bottom (which you can just see at the top of the field of vision — don’t forget it’s inverted). The refractive index of the gas is all wrong, and you really don’t see much at all: light and dark, vague shapes. But even now, I could tell that I had all the field of vision back. Never have I been more pleased to see the end of my nose.

The gas is absorbed slowly by the bloodstream and the boundary line between gas and water moves down. Two weeks on, I’ve still got a small bubble (which a few days ago was acting like a lens in its own right, giving me really amazing close-up vision when I looked straight down). As the detachment was large, the vision is a little distorted: straight lines have a small kink, and the perceived image is slightly squashed compered with the left eye. It’s like using a pair of glasses that aren’t quite right: it’ll take a few months, but apparently the brain does get used to this eventually, to some extent at least. Until then, don’t be surprised if you see me reading, programming or playing with an eyepatch — and don’t worry, I won’t be upset if you’re moved to talk like a pirate when I’m around.

Complications? Well, there’s a 15%-or-so chance that the operation will not have worked, and will need to be repeated. If it’s failed, I think this will be clear pretty quickly, but at present it’s all looking good. The procedure’s also associated with an increased risk of cataracts (which can be dealt with surgically easily, if they arise. And it’s better than losing the sight of an eye.)

Lessons for my readers? Most importantly - be aware of the early symptoms! A steady or sudden increase in the number of floaters in your eye (if I’d known this, I may have gained a couple of days) is a giveaway. Something I’d noticed but discounted a few months before is apparently also an early sign: close your eyes or sit in a dark room, and shake your head. I’d seen a bright flash, like someone momentarily opening a door to a brightly-lit room, at the edge of my vision. It’s called photopsia, most commonly caused by shrinking of the vitreous, and might, particularly if you’re not as young as you were, or even as old as me, suggest you should have it checked.

Lastly, acknowledgements — firstly to Chau-Yee, who’s looked after me lovingly: kisses. And to my surgeon, Mr Paul Sullivan, with thanks for a job well done. To our neighbour Ollie Smith, for the first ride down to Moorfields! And finally, to John McIntosh, to whom I’d promised this blog.

“Why not?”

“We agreed at the beginning of the release that you would do it like this“

“Ah, but doing it like this makes no sense now.”

“Look, in the meeting minutes. You agreed!”

“So? We’ve learned a lot since then…”

“But you can’t do it like that!”

Bureaucracy hates self-organisation.

Berkun makes some interesting observations on using this for feature discovery and refinement — design for flexibility, then set things up in your prototypes and early versions to record what people actually use. There are — of course — team and organisational analogues as well. Joseph Pelrine introduced me to Social Network Analysis in a project retrospective I’d asked him to run for us at Sibelius, and later at a SPA conference session. It’s a great way of holding up a mirror to a group, and revealing the real patterns of interaction amongst its members, regardless of formal roles and responsibilities.

Ralph Stacey takes this idea further, and talks about the Shadow System:

[The Shadow System] is the set of interactions among members of a legitimate organisational system that fall outside that legitimate organisational system. It comprises all social and political interactions that are outside the rules strictly prescribed by the legitimate system. It is the arena in which members of an organisation pursue their own gain, but also the arena in which they play, create, and prepare innovations. (Ralph Stacey, Creatitivy and Complexity in Organisations, p.290)

There’s an immense amount of food for thought here. According to Stacey, the degree to which this shadow system is tolerated or even encouraged by the legitimate organisation has a direct influence on the organisations creativity and resilience. On the contrary, an organisation which imposes its bureaucratic structures with the force of law stifles innovation (and in some cases, it’s the permanent and baffling acceptance of this status quo on the part of the members of that organisation that sustains this: it’s as if every single person in the company is terrified of stepping off the path. A park in which everyone “keeps off the grass” is a lifeless place).

What sort of organisation do you work in?

At one point in the introduction, Sondheim says:

…I think the explication of any craft, when articulated by an experienced practitioner, can be not only intriguing, but also valuable, no matter what particularity the reader may be attracted to. For example, I don’t cook, nor do I want to, but I read cooking columns with intense and explicit interest. The technical details echo those which challenge a songwriter: timing, balance, form, surface versus substance, and all the rest. They resonate for me even though I have no desire to braise, parboil, or sauté.

I wonder (he wonders) whether a book on software that could hold a general reader so could possibly exist?

And how’s this for a set of fundamental principles:

Content Dictates Form

Less Is More

God Is in the Details

all in the service of

Clarity

without which nothing else matters.

I’d be happy to sign up to those, in music, in writing, in software and product development.