Thursday, December 29, 2011

Don't be a 15th-century Venetian bank clerk


Reading the excellent "Double Entry" recently I came across the following quote from Summa de Arithmetica, Geometria, Proportions et Proportionalita (no, I haven't read it either. Or am I being presumptuous?), written in 1494 by the Godfather of double-entry bookkeeping Luca Pacioli, on the subject of unreliable office workers:
"...in these offices they often change their clerks, and as each one of these clerks likes to keep the books in his own way, he is always blaming the previous clerks, saying that they did not keep the books in good order, and they are always trying to make you believe that their way is better than all the others, so that at times they mix up the accounts in the books of these offices in such way that they do not correspond with anything. Woe to you if you have anything to do with these people... Maybe they mean well, nevertheless they may show ignorance."

Sound familiar? As Jane Gleeson-White - author of "Double Entry" - says, "Nothing much has changed in five hundred years." There are any number of IT people who rather than spend a bit of time and effort learning how and why their immediate predecessors, the people who worked on the code before they did, did things assume that they know best and mix up the code by adding their own unnecessary bits "in such way that they do not correspond with anything". The code becomes more complex, but the net contribution is a negative one. The code doesn't do anything it didn't do before, but it does it in more ways now. Ever worked with one of those clerks? Ever been one? C'mon, be honest. Yes, and yes, right?


Nothing ever changes, it seems. Doubtless there were impatient Cro-Magnon guys who claimed their way of lighting a fire was the best, and that the last guy who lived in this cave couldn't rub two sticks together to save his life. At this stage it's appropriate to quote from another towering figure in the world of ideas:
"There's a subtle reason that programmers always want to throw away the code and start over. The reason is that they think the old code is a mess. And here is the interesting observation: they are probably wrong. The reason that they think the old code is a mess is because of a cardinal, fundamental law of programming: it’s harder to read code than to write it.
Yes, Joel Spolsky got here before and wrote the definitive post about medieval clerkly behaviour. So the next time you see some unsupervised codefreak reinventing the wheel, badly, and mouthing off about how the code's a mess, and they should have used this and that great framework etc., just say to him (and it will be a him): "Hey droog, what are you - a Renaissance-era Florentine municipal loan bank quill-pusher? Use the StringUtilities class like the rest of us!".

Tuesday, December 13, 2011

A simple jQuery StackOverflow client

In the course of writing my last blog post, I decided to make a simple Stack Overflow client. Who doesn't love Stack Overflow? Here's how to do it, in case you're interested.

I've been thinking about links, as in web page links. I've also been thinking about questions. So I decided to think about what it means to link to a question.

Most links are to answers, or at least statements about the world, such as a news article, a wikipedia page, a technical explanation, or of course an update about the Russian Phobos-Grunt lunar explorer. There aren't as many links to questions, because there aren't as many webpages that are questions. Links can't tell you anything about their destination page other than what the author of the web page on which they appear chooses to reveal, and what they show in their URL structure.

Using the Stack Overflow API

So, say I'm writing a blog post and I'm talking about MVC3. I can link to a Stack Overflow question about data annotations like this:
"...So, you may ask yourself, how does data annotations really work in MVC. This is an interesting question..."
That links to a question I've favourited on Stack Overflow. But it might be nice to link to it like this:
"...So, you may ask yourself, how does data annotations really work in MVC. This is an interesting question ..."
That's because with a question, particularly a tractable one (unlike "What is the meaning of life?") like in the example, it's nice to know whether it's been answered before you click on the link. How many times as a developer have you wasted bandwidth and your patience clicking through on links thrown up by Google searches for questions that have no answer on crappy forums, spamming the answerspace. The question's meta-information, such as how much reputation the asker has and how many views its had may help you decide whether to click through to see that page.

Anyway - to the matter at hand. I thought it might be nice to show the code for embedding a question like this in a web page, because it's really quite simple, yet there are a couple of small points of interest worth paying attention to.

The HTML

To get the questions to appear in a page, I use a span or a div, with a custom data attribute supplying the question id:
"...So, you may ask yourself, <[span/div] data-question-id="5154231" class="StackOverflowQuestion">how does data annotations really work in MVC</[span/div]>? This is an interesting question...
I obviously have to go off and get the id of a question I'm interested in from the URL of that question in advance because the endpoint I'm interested in is "/questions/{id}". As a precaution against clients that don't execute Javascript, most notably Google Reader, I include the text of the question as the default inner contents of the span or div so it at least fails nicely.

Somewhere in my page I also include a reference to the Javascript file responsible for putting it all together, StackOverflow.js:
<script src='http://www.connemara.com/Scripts/Blog/StackOverflow.js' type='text/javascript'></script>
Let's look at that Javascript file now.

The JSONP

In a nutshell, all this JS file does is find any spans and divs on the page it serves that have the HTML5 custom data annotation "data-question-id" and makes a JSONP request to a Stack Exchange API endpoint with the id of the question, showing loading content until the request is succesful whereupon it formats the question metadata according to whether the original element is a span or a div.

Because I'm making an AJAX request from my site to api.stackoverflow.com, I have to use JSONP to get around the same origin policy restriction. I could use normal JSON if the endpoint I was hitting was on the same server as my calling code, but of course in this case it's not. Luckily, the Stack Exchange API supports JSONP calls, with the small stipulation that you use the "jsonp" parameter (normally, the name of this parameter is up to you). That's why you see the line: jsonp: "jsonp" in the AJAX method below.


I believe it's pretty straightforward what's happening here. But as I hinted at earlier, one of the major drawbacks of doing this sort of Javascript content insertion, especially for blog posts (which really shouldn't be surprised to find themselves in an RSS reader), is that Google Reader can't use them. Yes, it's a biggie. That's why I need to have decent default content for those spans and divs. I've written to Google to let them know their site's broken.

Tuesday, December 6, 2011

Visual Studio 2010 Screen Redraw Hell

If you have been having problems with Visual Studio 2010, then maybe you have the same problem I had.

Lately I've been having all sorts of problems with Visual Studio 2010 (Ultimate) at work. It's been making me miserable. I believe some days my problems have made my team miserable too. You see, I'm not the sort of person to stoically endure a bad situation quietly when I could trumpet my dissatisfaction to anyone within earshot.

My problems start when I get the latest changes from Team Foundation Server. TFS is ... well, you wouldn't have read this far if you didn't know what TFS is, so let's skip that part. Anyway, if I can get past getting latest then depending on how long it's been since I last got latest I'm usually onto the resolve conflicts "dialog". Why the scare quotes? A dialog is when (at least) two people are talking. This is when the pain hits.

A series of small dialogs appears, advising of merge conflicts, or asking whether to accept the merge resolutions I have just made. This is when all crap breaks loose and Visual Studio/TFS starts hanging, crashing, not responding, and generally wrecking my buzz. I can accept a merge resolution by clicking 'Ok', only to have that window reappear and ask the same question over and over - just like my 4-year old son Eoin - before the whole mess o'windows becomes totally unresponsive. Viewing the sprint backlog is painful in a different way. The items would appear line-by-line as each agonising second ticked by. Then if I scrolled up or down, more of the same.

SO Question
But before Visual Studio crashed for good, strange clues appeared. For example, in my frustration and impatience I sometimes idly clicked some of these merge windows and dragged them, and noticed that the dialog would go away, resolved. Hmmmm. Also, as VS thrashed about in its death throes, the desktop icons would disappear and reappear, and disappear, and reappear...

So, did it have something to do with graphics? And therefore not network latency as I'd assumed? And what was this I heard about WPF? I never thought of VS as being something that might need the assistance of a graphics card, but it seems it does. I noticed, in contrast to my colleagues, I had no dedicated graphics card. And that was the difference. I was in screen redraw hell.

Acknowledgement: I must at this juncture point out that it was a colleague, the man I call 'Andrew of a Few Desks Away', that helped me realise all this and who showed me how to fix it. I owe him a doughnut and a follow on the social media platform of his choice.

The bottom line

Tools -> Options -> Environment, General. Check 'Use hardware graphics acceleration if possible'.

Sunday, December 4, 2011

Stick it in the wiki

We're a few months into the project and it's already happened. We've stopped doing documentation. We're programming, we're doing our TFS due diligence, we're writing our self-documenting tests. All good stuff. We're hitting Stack Overflow hard, but we're not really documenting anything. We're having spirited discussions about coding standards, but we're neglecting our shared documentation repository. We're struggling with gnarly integration problems between different platforms, we're writing in-depth emails to each other, but we're not taking a step sideways from the code and introspecting as we should. We're not bad people, but we're busy right now. We'll get to it, ok?

We're upgrading to @ReSharper 6.1 but we haven't contributed to the written culture of our team all week, hardly ever. We've just stopped. We all agreed when we started that it's something we should be doing, so therefore this hiatus is not borne out of any ideology, but rather is just a collective shrug of the shoulders.

What does it mean when a team starts neglecting the documentation aspect of their work, when they ignore their written culture?

Flickr photo
FlickrPaul Bourget (LOC), by The Library of Congress. Writing. It's what we do. Stick it in the wiki.

Are you part of the problem?

Like many a place I've worked in, we have a developer wiki here. I call it a wiki because that's what people call it, even though it's not really: it's a Sharepoint CMS. And like many places it languishes in obscurity as we work to get through our sprints. This is probably inevitable, as early development is characterized by rapid progression and scaffolding up initial infrastructure.

But before complaining about a problem, I find it a salutary exercise to examine my own contribution to it in the first place. For my part I quickly added some content to our team wiki, but then as quickly forgot about it. I went off and set up a group Diigo account and a Google+ Circle. That was because I think that links belong in a social bookmarking site like Diigo or Delicious, and Google+ is good for quickly hitting up the other guys for quick questions, etc. But I also let the wiki slide a wee bit because - yes, I'll admit it - it's not sexy, our poor old CMS. It is simply a fact that Sharepoint is uninspiring and unattractive, at least to devs that I've met.

It really is something only a mother could love, our wiki. Restricted to using IE unless one wants to hack away directly at the HTML whenever one makes a contribution, unless of course one is feeling fortitudinous enough to paste example code in, in which case manual HTML hacking is the rule whatever the browser, one approaches the wiki with fear. And since this is Sharepoint-generated-HTML I get the F.E.A.R. every time. Crappy old tech can turn people away from doing something they should be doing.

So can uninspiring motives: one way the purpose of a developer wiki has been explained to me is as something we'd need if a new developer joins our team, maybe because one of us is hit by a bus. If that's the main justification for your wiki, it's hardly surprising that devs concentrate more on solving immediate problems and less on worrying about implausible catastrophic hypotheticals. If they think of it as a resource they themselves will need before too long as the project gathers complexity then they are much more motivated to cultivate their project's written culture lovingly: it's in their own interest to do it, not in the interest of someone they haven't met yet.

My last job

In the last place I worked in, they had a strange relationship with their wiki. The devs begrudgingly acknowledged its existence, and would wonder at your naivety if you actually tried to follow any of the processes contained therein. After Brad, the tech lead, left in frustration two weeks after I started, it fell upon me to take over and maintain the wiki. I say take over, because it had been hosted on Brad's machine, which was now no longer switched on. I tried tidying the pages up, correcting some of the more egregiously out-of-date articles, and so on, only to be told at a morning stand-up that I "was not being paid as much as I was to edit a wiki". I said, fine: then please stop referring me to it to find out how things work, when everything in it is so clearly wrong. Let's have the new guys go around and waste people's time asking them why this does that, and why that goes over there, etc.

This was a team in deep trouble - during my short 4-month stay there were several departures before - mercifully - a troubleshooter was called in to salvage the whole enterprise. At one stage, two of the devs who were determined to flag their independence from everyone else in our team maintained a separate page with steps for - oh I can't remember - something to do with database scripts, and were allowed to get away with their passive-aggressive behaviour in the face of entreaties from me to put their work in the common repository. This was a team whose members couldn't bring themselves to agree on how to share information. The state of the wiki was a good indication of the culture of the team, and of the poor health of the project.

Overreliance on Stack Overflow

It's not as if the idea of reading about how to do things is an alien concept to developers in their day-to-day work. It's just that Google is so good that people find it easier to search for information by keyword than try and find it in the in-house repository. Nowadays, Googling for programming information usually means one thing: all roads lead to StackOverflow.

Like anyone interested in programming, I love Stack Overflow. It's been such a positive force for good since it hit our screens around 3 years ago. Nonetheless, I think it's a shame to see devs constantly browsing SO at work. Which you do. I mean, is SO going to be able to tell you why you've just wasted half an hour trying to get a service call to the in-house service working? Maybe, maybe not. But since this sort of boundary between different layers is where trouble can often arise, it's vital that any hard-earned wisdom here gets wiki'd. And that it's the first place devs look when they hit trouble.

Stack Overflow is fine when you have a discreet technical problem that has nothing to do with your project's particular configuration, but even then after a bit of browsing around for the right question (and of course, answer) you nonetheless probably want to document that issue, with its Stack Overflow Url (ooh, lovely and clean MVC route) in case someone else hits it, or you do again.

Flickr photo
FlickrJoel Spolsky and Jeff Atwood present at MIX09, by D.Begley. You guys are spoiling us.

Of course, the other case where you want to document your Stack Overflow activity is if you have actually asked a question and got a decent answer or two. This is harder than you'd think sometimes. But if you have successfully crowdsourced a small part of your work of course you should allow the other people in your team to find out about it without them having to accidentally stumble upon it. Hello wiki.

Keep the noise down

As important as it is to generate content in your wiki, it's also vital to do some gardening, to clear out the weeds. This week I took a look at a couple of pages I'd written very early in the project, and to say they were irrelevant to what we're doing now is being generous. Gone. Deleted. Turn that noise down. These pages were borrowing from devs' goodwill and patience, and repaying nothing.

None of this is easy. None of this is for free. Not every web developer likes to write. Not all of them blog. Many barely tweet (C'mon Sandra - do it!). And even if they did, they may not see the value in burying articles in a company wiki, too often a cold, forlorn place where knowledge goes to die.

If you have a dominant developer or a tech lead who doesn't like to document stuff, or just doesn't have the time, you may end up playing Boswell to his Dr. Johnson. Wiki as project biography. Without the wigs, hopefully.

But here's the thing: if you keep a good enough wiki, Sharepoint CMS, team blog, or whatever form your team chooses to document its work, you might end up with several blog posts worth of material practically written for you. Whether you are blogging from a low-level technical level, or more from a project management or architectural one, it should be all there: the reason you switched from Ext.NET to jQuery UI, afternoons spent arm wrestling with Entity Framework Code First, a love letter to ELMAH. Maybe if only for that reason, a dev might decide to really commit to the team wiki. As long as it's in there, it doesn't really matter why you're doing it.