Arnt Gulbrandsen
About meAbout this blog
2017-01-25

Audience and goal

Written texts have two major invisible properties: audience and goal. I can't remember who taught me about that, but I taught it to my friend Abhijit Menon-Sen when we started working together, and the texts he and I have written together over the years always have a hidden comment describing the audience(s) and goal(s) for that text. That's why those texts are crisp and to the point.

Here's an example. Not by us together, this one is his alone.

Abhijit and his girlfriend Hassath have recently built a house, it's aaaaalmost done now, and a few weeks ago Abhijit wrote a blog posting about an electric power gadget they bought for the house. The audience for that posting consists of two groups of people: Friends who want to know how the house is coming along, and people who are searching for reviews of the gadget before possibly buying one themselves. The goal for the first group is to describe the power problems and how Abhijit and Hassath are coping, and for the second group, to tell them whether and how well that particular gadget helps with that kind of power problem.

Now please read about their amazingly unreliable power supply and consider how each sentence, each paragraph and each picture helps with either or both of those goals, in the eyes of those audiences. Does a sentence say something that both audiences already know, or does it tell either or both audiences something Abhijit wants to tell them? Does a sentence help with one goal but disturb the other? What does the photo achieve? Would mentioning the audiences or goals in the text help to achieve either of the goals, or would it distract or detract?

That posting may be stylistically vapid, but it achieves Abhijit's goals and that makes it good writing. The rest is a mere question of how good.

Now please start formulating an explicit audience and goal before you write your own email, documentation, almost anything. Help save the world from pointless blather and documentation that forgets the critical points.

2016-09-01

Code review times two

I like code review but complain about it all the time. Why? The other day I had an eureka moment: There are two quite different kinds, which I will give the misleading names agile review and waterfall review, and I'm annoyed when the reviewers perform one kind of review and I want the other.

Waterfall development is centered around planning, development and deployment in stages: First plan well and get rid of most bugs, then implement what's planned, then review and test to fix the remaining bugs, then deploy. In this model, code review focuses on catching minor bugs, ensuring code style harmony, proper use of internal/thirdparty APIs, etc. Big questions such as is this feature a good idea at all? are out of scope, because that's been settled in the planning phase. (I'm not saying waterfall works in practice, only describing the theory.)

Agile development is different. Instead of planning well, agile development is based around an iterative process: Implement something that seems to be a good idea, consider it, learn something from it, finish it and then deploy, then pick something else to do, something one now knows more about. Code review can be the first part of the consideration and learning process, so it's a good time to discover that although a feature seemed like a good idea, it's going to be a morass and should be dropped at once. (more…)

2016-08-04

Life goes on

This autumn my work shifts from arthouse pixels to mass-market pixels. An occasion to post this remarkable photo:

It reminds me a little of a more modern descendant of the sparse modernist interiors, but sparser, sparser, and with a giant screen instead of art.

The picture comes from an advertisement. You're assumed to like the interior, and you're meant to buy the TV. Too late, that model is not on sale any more.

My work involves avoiding some things you don't see on the photo: A settop box and a hundred-button remote control. Less frustration, more reliability, better usability.

2014-07-24

Agility for responsible adults

It's a bit of a pity that the waterfall model of software development is out of fashion, not? But maybe it's possible to tweak scrum/agile development to be almost like waterfall? What would be necessary?

First, introduce cycles and milestones to more or less replace the continuous delivery. Adult supervision requires setting goals. It's okay to run CI tools, as long as you have at least a couple of future magic dates, call them next step along the waterfall and final arrival at the ocean or call them internal/partner alpha launch and public launch date.

Do it right instead of the continous improvement. The waterfall model says that it's cheaper to fix bugs earlier, so do it right once and it'll stay right. This too is simple to integrate into Scrum, just boost the code review and pre-implementation consultation. Talk about how important it is to have the right design and to avoid technical debt. Make technical debt seem worse than the many other kinds of software deficiencies. (more…)

2014-05-14

Is this going to bring any results?

Most readers will not have visited the world's largest city: Kiruna, in northern Sweden. It's bigger than Wales, and snowier as well.

One dark winter afternoon, which in Kiruna is very dark indeed, Medel­svens­son was going home from work when he met someone outside the entrance to the office building, searching for something in the snow. Hi, have you lost something? My car keys. I'll help you look for them. (more…)

2014-02-17

Good unit tests, bad unit tests

The author of the most pleasant java code I've ever seen wrote the following paragraph on an internal mailing list last year, or perhaps the year before:

By the time I met my last significant mentor I had been programming for 15-16 years. I was skeptical to much of what he wanted me to do, but I shut up and gave it a few weeks — eventually incorporating much of his thinking into how I work and evolving my own style. He was amazingly bad at explaining things verbally, and to be honest: his code looks like shit. But he kept coming into my office and demanding all the right things of me; that I think about what I output (seriously, do you need that log output!?), that I have near 100% test coverage even if it means the test code is 5 times larger than the code it tests, that I always remove code that isn't used, that I never implement methods that I don't need right now, that all public methods and classes are always documented and that the documentation be kept in sync with the implementation, that the code will build and run its tests on any machine and without screwing over other developers by assuming what is and isn't installed on the machine, that it compiles without warnings, that software is trivial to fire up, that any and all performance critical code is benchmarked, that code is never prematurely optimized but that design-work always consider performance implications of choices etc etc. I got yelled at every day for at least 3 months.

That mailing list was internal to a company that cared deeply about doing all the right things, avoided almost all of the cliché mistakes and yet missed deadlines serially. (I didn't know it yet, but later, the company would cancel its main product, weeks before release.) The demanding mentor was someone whose code looked like shit, yet demanded all the right things. There were parallels there, I thought, maybe I could use one to learn about the other. So I put it aside for a think and a ramble. (more…)

2013-10-17

Reviewing code and people

Some years ago an Indian friend of mine was invited to speak at a conference here. He applied for a visa, then the visa application was rejected. He got someone to phone around behind the scenes, and learned the real reason for the rejection.

The decision made sense.

My friend was an expert in his field and could easily get a job here. The fact that he was invited to speak at that conference proved his expertise, and his connections here proved that he could easily get a job. Further, my friend was single (on paper), did not have a highly paid job in India, and he was young and easily able to move. The visa application reviewer quite sensibly inferred that that my friend had the option of not returning.

The visa application reviewer used this decision matrix when processing the application:

Application accepted Application rejected
Friend planned to return Neutral None
Friend planned to overstay Negative None

This matrix leaves out the impact on the conference and on my friend, because their interests did not matter when the decision was taken. The government at the time really wanted to reduce the number of people who overstayed their visas, and almost ignored other factors when it made the decision matrix. It didn't particularly care to please my friend, or to displease him, it wanted to reduce the number of overstayers.

It's easy to curse the xenophobic so-and-sos who guard borders, but when I look at that matrix, I can understand why the reviewer decided to reject the application, if the chance of overstaying seemed even just a little above zero.

Code reviews are like that in some companies. They can be easy to curse, too.

Patch accepted Patch rejected
Patch works Neutral None
Patch is broken Negative None

Given that matrix, of course each and every meeting is more important than getting progress on the patch. Of course any minor objection is enough to block the patch or ask for another revision. Some people say things like if you haven't found any problems, you haven't reviewed properly. I think that when someone can say that with a straight face, the team is secretly using the decision matrix above.

For the next visa application my friend changed the matrix. Among other things, he arranged for a Sir Humphrey Appleby to telephone the consulate and explain that the minister hopes you will treat this young man favourably.

Application accepted Application rejected
Friend planned to return Neutral Minister displeased
Friend planned to overstay Negative Minister displeased

My friend got his visa. It's always good to have friends in the foreign ministry. It's good to have an appropriate decision matrix, too.

I have no simple hack to balance the matrix for a code review. But balance is necessary, that's one of the keys to useful code reviews. If the matrix is skewed one way, the code will stall, if the other way, it will acquire too much technical debt.

2013-05-08

Someone should

The should rules went out of fashion at Trolltech after I left. I don't know when, but some people who started in 2006 didn't learn them.

Which is a pity, they were good rules and in my opinion they still are.

The rules were: In a meeting (which at early-Trolltech usually meant over lunch), the phrase we should … meant I will …, and someone should … meant I immediately will ….

The rationale for this is what we should and someone should was weasel wording for I think we should …, but I know I can't persuade anyone else to take on the work. Often (but far from always) noone else thought the result was important enough to justify the working time. Sometimes there were many other reasons. But the reasons don't matter, the results matter, and the should rules made people speak more realistically.

For what it's worth, the rules were suggested by Paul Olav Tvete.