(Just by coincidence, this post also has a cardboard theme, but is unrelated.)
A “Cardboard Programmer” is a fellow colleague to whom you explain your current programming problem in the hope that as you give the explanation the solution will come to mind. Your colleague usually doesn’t have to do anything except stand there and listen, which is why some programmers will suggest that a cardboard cutout of a colleague will suffice.
In practice, a cardboard cutout will not suffice. I’ve tried. Apart from the sense of stupidity of talking to oneself, there is a certain lack of intensity in the act of giving an explanation to an inanimate object. The flesh-and-bone (F&B) variety of cardboard programmer is without doubt the most effective. But why?
The most obvious reason is that the F&B can give you quizzical looks if your explanation isn’t up to scratch, so you are less likely to skip details or make too many assumptions. With a F&B programmer you are under even more pressure to be clear and precise, and this in itself is conducive to you finding the solution.
In a way, this is why I extensively document my code. I know this documentation may one day fall into the hands of another programmer who will have the unfortunate task of maintaining it, upgrading it or (however unlikely) repairing it. I picture this person from the future as a F&B cardboard programmer standing at my shoulder, and the last thing I want is some quizzical looks.
Many years ago, as a lecturer, my students learnt that I would fail them for poor documentation, no matter how good the code was. They would complain initially that they didn’t have time to do the code and write the documentation. But in time they found that writing the documentation (preferably first) reduced the overall time to completion, and greatly reduced errors. For me, having to look at thousands of programs submitted by students, it impressed on me the huge importance of clear code with clear explanatory documentation.
I recently had to dig into some legacy code that was sparsely documented and unfortunately it was proving difficult to decipher. After a few hours I found myself trying to explain out loud what I thought I understood. (I was at home; nobody was listening.) This viva voce approach was getting me nowhere. I thought perhaps writing it down would be better, but again that felt like I was talking to myself and it just didn’t have that edge I needed.
Then I thought about using a colleague as a CP via email. Sure, he wouldn’t read it until perhaps the following day, but like code documentation, the pressure of knowing that a competent colleague capable of making quizzical looks would see it…
And so started a short sequence of detailed emails in which I went from total bewilderment, through realization and eventually to solution, which I’m glad to say appears to work perfectly. I’ve had no replies to the emails (yet), though that’s not usual for cardboard.
More than 30 years ago, when the revolution of personal computing was just beginning, I was one of many young people who knew what they wanted but found it just a little bit beyond grasp. Sometimes the challenge was availability, with many of the early PCs only available in certain models, in certain markets. Sometimes the mail order would only deliver to certain places. Often the barrier was simply the price, despite the efforts of Sir Clive. For me, DIY was without doubt the only option, as ready-made PCs were far too expensive. And so it was that I found myself spending most of my time with circuit designs, rough program outlines and plenty of cardboard mock-ups of the cases I might create, depending on which computer I might eventually build. Hand-drawn circuits, hand-written programs and cardboard computers. I did eventually build several computers, even some pretty powerful ones, but there was a certain special kind of excitement that comes with the cardboard phase that I thought my kids would never experience.
It seems I was wrong. Three decades later and some of my contemporaries have succeeded not only in recreating the buzz of the early days of personal computing, but in their adherence to the bare-bones philosophy they have resurrected the cardboard computer. I speak of the Raspberry Pi, the $35 /€30/£25 credit-card-sized computer. My kids want one. (I want one!) Since it comes without a case, there’s great interest in creating home-made cases. My younger son presented me with a life-sized paper model of what he wants to build, and he’s keen to learn how to shape Perspex. My older son is intrigued by the idea of mounting the Pi inside a keyboard, reminiscent of the old Commodore 64.
Thirty-odd years later, it’s like nothing has changed, and I’m loving it.
A number of years ago I wrote a program for the W3C to automatically migrate a Moin-Moin wiki to MediaWiki. At the time, I was the Chair of one of the W3C groups and we had just decided to replace our wiki technology because participants were finding the limitations of Moin-Moin to be a problem. Similar complaints were heard from dozens of other groups in the consortium and it was inevitable that we would have to find a way to reformat thousands of documents. Furthermore, since the W3C insists on accurate records of the evolution of the technologies in its care, we would have to migrate every version of every document. The entire history had to be preserved. And at the same URLs, if possible.
Doing it manually was just impossible, even for just our own wiki, never mind the whole collection of wikis in W3C. Since it was obvious that this was going to be a pain point for many groups, I resolved to write code to migrate my group’s wiki and make the code configurable enough to handle any wiki.
I’m happy to say the solution worked for the DD group wiki, and following that success I donated the code to Open Source (under the W3C license). Since then the code underwent some minor updates to keep up with MediaWiki changes. Some people were charmed by the results. (It’s nice to know that someone outside W3C found it useful!) The most recent update by Rufus Pollock went up on GitHub in the middle of 2011. The W3C did eventually use the code to migrate the entire collection of W3C wikis in its care. They even took the time to write a short manual of how to use the tool I created.
Which brings me to the subject of documentation.
The mm2mw solution was written in Perl, one of a few programming languages that can be a joy to use, but also comes with huge risks of creating code that few can decipher. Including the author! Since nothing annoys me more than poorly commented code, I tried to make it reasonably structured, with sensible naming and plenty of comments, hints and explanations embedded in the “tricky” areas. These comments are as much for me as they are for others who might maintain my code. But the truth is that I seldom return to my old code, so I don’t normally get to discover how successful (or unsuccessful) my documentation has been.
The other day I was clearing out some of my old code archives when I came across a copy of mm2mw. “I remember that,” I thought, and out of curiosity I opened it up. So, after a number of years gathering dust, here are my first impressions as I scrolled through my old code:
What the…?
ASCII pictures of the directory hierarchies used/created. So glad I put those in.
It even generates its own help file when it has finished, so you know what to do next!
20% of the source is preamble/explanation at the start. Keeping the doc as close to the code as possible.
Another 20% of the source is the interactive UI. Nothing complicated so far.
Ouch. Around line 400 it starts to get hairy.
Relying heavily on “meaningful” variable/subroutine names. These lines are wide!
Have to read slowly. Line… by… line…
Did I really write this?!: if ( $x =~ m/^\s*((<.[^>]+>|<\(>|<:>|<\)>)+)(.+)/ )
Now I’m really having fun!: s/(?<![\&!\/#])\b([A-Z][a-z0-9]+){2,}(\/([A-Z][a-z0-9]+){2,})*\b/[[$&]]/g;
At this point I remember how to spin the scroll wheel on the mouse. My head hurts.
The source reads better colour-coded on GitHub, but it’s still quite rough to read. I thought at the time (2007) that I’d done a reasonably good job. Just as well the program works and has needed very little maintenance, as I’d sure feel sorry for anyone who has to pick up where I left off!
Virtual hosting is a great idea. Many sites, sharing a smaller number of servers, making maximum use of resources. Generally it works. But there are times when sharing becomes a problem. When your site needs resources that are also simultaneously needed by the co-hosted sites, the conflict manifests through slowing responses. The backend of one of the sites I manage in my spare time (ha!) has an occasional need for intensive database queries, and I had noticed that sometimes the responses were particularly slow. Closer inspection showed the problem was not down to bad indexing, or bad joins, or any of the usual suspects. Memory and CPU didn’t seem to be a problem, but the CPU resource usage reported by the system was relative to the virtual server, and didn’t reflect the actual level of processing capacity being made available by the host environment. It turned out that the co-hosted sites had changed their backend implementation and were now making use of more server-side processing, and had also added encrypted connections, greatly increasing the processing overhead.
The site has shifted to a less-shared environment, though it’s still not perfect. What I really need is a hosted environment with some minimal level of service guaranteed, regardless of the neighbours. There are clouds that can offer this level of guarantee, for a price, but it may be my next move.
Google recently released a version of Chrome for the Android 4 OS. While it is always good to see the latest Web technology being extended to the (relatively confined) domain of mobile devices, one of the most welcome features of this latest mobile browser is its comprehensive developer support. With the help of a USB cable and a suitably configured PC, you can now effortlessly develop eye-watering mobile Web experiences. Included are all the usual favourites, such as DOM navigation, real-time DOM editing, real-time CSS editing, CSS enable/disable, call tracing, script debugging and so on.
The new Chrome is still in beta, and only available for the latest incarnation of Android, so the impact will not be felt as widely as other browsers. No doubt this will change quickly as Google have an aggressive roll-out schedule.
There are a few important points to note:
Those concerned with privacy should note that there is a report that the browser continues to use GPS when it is running in the background.
Meanwhile, those concerned with security will be concerned to hear that SSL support is broken.
There are some reports of the browser crashing. This would not be unusual for beta software. Take care if using Chrome to do anything important.
Flash is not supported, and will not be supported. Flash for mobile is dead.
You can detect a Mobile Chrome request by looking for “CrMo/” in the User Agent header.
The address bar is permanent. You can’t hide it. Some mobile site designers will be very annoyed…