Just A Summary : Tag practiceofprogramming, everything about practiceofprogramming

Just a thought

pdcawley@bofh.org.uk (Piers Cawley) — Thu, 25 Sep 2008 23:46:00 -0500

There’s a refactoring principle that states that, when you start doing the same thing for the third time, you should refactor to remove the duplication.

I’m starting to wonder if there’s a Smalltalk principle which states that, when you start doing the same thing the second time, you should search the image for the obviously named method (or use the method finder to find some candidate by feeding it some inputs and an expected answer), because the odds are good that it’s only the second time for you – it might be the millionth time for the image you’re working in.

Get sophisticated

pdcawley@bofh.org.uk (Piers Cawley) — Wed, 20 Aug 2008 11:25:00 -0500

Ruby’s primitives (Strings, Hashes, Arrays, Numbers – anything that has a literal syntax) are fine things. But that doesn’t mean you should use them everywhere. You’re often much better off wrapping them up in your own Value Objects.

Something I was working on at Railscamp this weekend threw up a great example of why it makes sense to replace primitives with more specific objects as soon as possible. Tom Morris asked me to take a look at Rena, an RDF/Semantic Web thingy.

The RDF spec describes two types of literals: a plain literal, which is a string with an optional language attribute and a typed literal, which is a string and an encoding (so the string might represent an integer, float, or anything else that your schema feels like expressing).

These literals can be output in one of (at least) two formats. We’ll start by looking at Literal#to_trix and see where that takes us:


def to_trix
  if @lang != nil && @lang != "" 
    out = "<plainLiteral xml:lang=\"" + @lang + "\">" 
  else
    out = "<plainLiteral>" 
  end
  out += @contents
  out += "</plainLiteral>" 
  return out
end

If we look over at TypedLiteral#to_trix we see a much more straightforward implementation:


def to_trix
  "<typedLiteral datatype=\"#{@encoding}\">#{@contents}</typedLiteral>" 
end

How do we eliminate that ugly conditional at the beginning of Literal#to_trix, and analogous conditionals in Literal#to_n3 and TypedLiteral#to_n3?

My first thought was that I wanted to be able to write something like:


def to_trix
  "<plainLiteral#{@lang.to_trix}>#{@contents}</plainLiteral>" 
end

But I didn’t want every string in the world suddenly acquiring a to_trix method. So, the solution was to intoduce a Literal::Language class and coerce our language into it, so Literal#initialize became:


def initialize(contents, lang = nil)
  @contents = contents
  @lang = Language.coerce(lang)
end

And Language would look something like:


def self.coerce(lang)
  if lang.is_a?(self)
    return lang
  end

  new(lang.to_s.downcase)
end

def initialize(lang)
  @value = lang
end

def to_trix
  if @value == ''
    ''
  else
    " xml:lang=\"#{@value}\"" 
  end
end

That ugly conditional’s still there though, so we introduced the Null Object pattern, and things started to look a good deal cleaner:


class Language
  class Null
    include Singleton

    def to_trix
      ''
    end
  end

  def self.coerce(lang)
    case lang
    when self
      return lang
    when nil, ''
      return Null.instance
    else
      return new(lang.to_s.downcase)
    end
  end

  ...

  def to_trix
    " xml:lang=\"#{@value}\"" 
  end
end

At this point, we’re still just pushing code around. If anything, we’ve got more lines of code now than when we started, but we’re starting to move behaviour nearer to the data it relates to, and our objects are starting to look like objects rather than data structures. So, we press on and make a TypedLiteral::Encoding class and, at this point things start to look interesting. TypedLiteral is starting to look almost exactly the same as Literal, but with an Encoding rather than a language.

That strange leading space in Language#to_trix is starting bug me. Let’s rewrite like so:


class Literal 
  class Language
    def format_as_trix(literal)
      "<plainLiteral xml:lang=\"#{@value}\">#{literal}</plainLiteral>" 
    end

    class Null
      def format_as_trix(literal)
        "<plainLiteral>#{literal}</plainLiteral>" 
      end
    end
  end

  def to_trix
    @lang.format_as_trix(@contents)
  end
end

If we make analogous change to TypedLiteral and TypedLiteral::Encoding it’s obvious that TypedLiteral and Literal were essentially the same class. Renaming @lang and @encoding to @language_or_encoding makes this blindingly obvious, so we’ll remove all of TypedLiteral’s methods except initialize. All that remains is to introduce Literal.untyped and Literal.typed factory methods to Literal, and make Literal.new into a private method and we can remove TypedLiteral in its entireity. So we change the specs to reflect the new API (wrong way round I know). Now we have a chunk of shorter, clearer code that will hopefully be easier to extend to cope with outputting literals in other formats.

Retrospective

I realise that patterns aren’t the goal of development, but by the end of the process we have a Strategy (Language/Encoding), a couple of Factory Methods (Literal.typed, Literal.untyped) and a couple of factoryish methods (Language.coerce, Encoding.coerce).

The most important aspect of the change was the introduction of the two new value object classes. Once they were introduced, they became the obvious places in which to put the varying behaviour and eliminate the repeatition of conditional code from the to_* methods. If there were to be a third output style, I would look at introducing classes like N3Stream, TrixStream and WhateverStream and have a scheme like:


def to_n3
  print_on( N3Stream.new )
end

def print_on(stream)
  language_or_encoding.print_on(stream, value)
end

but that’s almost certainly over complicating things right now.

The other thing I like about this kind of refactoring is that it drives the code towards methods and classes which obey the single responsibility principle and, at the end of the process, not only do we have fewer lines of code in total, but the individual methods involved are all substantially shorter and closer to the left hand margin.

I really should start doing this kind of thing more in my Rails practice – I keep being put off by the fact that the composed_of helper is so annoyingly not quite right and, rather than submitting a patch or making a plugin I go “Ah well… I can live with a string for a bit longer…” and I know. From hard won experience at that, that it’s going to come and bite me. It’s already bitten Rails recently when Ruby got a new String#to_chars which doesn’t work like the ActiveSupport version.

Notes

If you want to see the gory details of how the change got made, Tom has merged this weekends changes into the github repository. It didn’t happen in quite the order I’ve described it in this post, but neither is this post a complete fabrication.

Changes

Corrected a stupid typo in the first block of code. Ugly condition is actually if @lang != nil && @lang != ''

Usability testing (throws) rocks

pdcawley@bofh.org.uk (Piers Cawley) — Thu, 03 Jul 2008 04:55:00 -0500

Usability testing is wonderful. But wow, its humiliating.

I’ve spent the last few weeks working on the Amazingtunes in page player. Amazingtunes is a music site, so we need to play music. However, we don’t like the way that most music sites work; either the music stops as you go from one page to another, or the player is a huge Flash app running in its own window. There has to be a better way. There needs to be a popup window if you want to eliminate stop/start behaviour, but there’s surely no reason not to keep the controls on the main page.

So, we set about writing somthing that did just that. We settled on using Jeroen Wijering’s excellent flvPlayer, which handles the media formats we need and has good Javascript control and communications. This sits in the child window and we use Javascript cross-window communication to have a player controller in the main window that looks something like:

Uploaded with plasq’s Skitch!

This is all done in HTML and and Javascript, the progress bar does the Safari trick of running behind the tune data links, the buttons do their AJAX magic and the whole thing is rather slick, though I say so myself.

At least, we thought it was slick until we pointed the usertesting.com legions at it. Without exception, they ignore the in page player, foreground the popup and use the teeny weeny controls on the flash player. Originally, the popup window didn’t even display any transport controls, it just had a picture of some speakers and some text asking the user not to close it because it was playing the tunes. We added transport controls as a stopgap while we made the in page player work properly.

I sound like I’m whinging don’t I? It’s certainly a blow to the ego to see something we spent so much time and attention on being ignored by our sample users. On at least one occasion, while watching the screencasts I found myself boggling at the things the users did, and if I didn’t shout “Just play some bloody music!” at the screen, then I came worryingly close.

It would be easy to retreat into a state of denial: “They’re not our target users! They’re stupid! They’re American! If they would only magically intuit the way we think they should use the site!”. And maybe it would be comforting to do so, for a while. The right thing to do is to suck it up – take away from those videos the sure and certain knowledge that bits of the site don’t work and do something about it.

We may dislike the ‘popup window for transport controls’ model of controlling music playback, but users are cool with it. And it’s not as if the work we did on making the in page player work is going to be wasted – widget is straightforwardly event driven so it’ll work just as well in the popup window, and the communication protocol will be much simpler. Having the player in its own window means we’ll be able to extend its interface in ways that would be hard when the player had to share window space with the rest of the page. In the end, it’s all good.

But… damn that in page player was sweet. I learned Javascript as I wrote it (mostly by pretending it was Perl with odd syntas) and I’m bloody proud of it. I’ll happily replace it with the next iteration (which I’m already working on), but it’ll be with a pang of remorse all the same.

Listen to the Voice!

pdcawley@bofh.org.uk (Piers Cawley) — Tue, 13 Feb 2007 07:31:00 -0600

You know that voice at the back of your head that says things like “That’s not really a data structure, that’s an object that is!”?

You should listen to it.

I’ve been battling away with having a million and one things monkeying with a result set that consists of an array of arrays, when really it should have been a ResultSet which has a collection of ResultSet::Rows. Once I bit that bullet, I got to do things like add ActiveRecord::Errors to each row and generally start to bring a bunch of big guns to bear on a problem.

So, having listened to the voice at last I’m going through and removing code with gay abandon. Sometimes I think removing code is one of the great joys of being a programmer – it’s the code’s way of telling you you got something right.

So, today’s slogan is “Reify early and reify often”.

Blessed are the toolmakers

pdcawley@bofh.org.uk (Piers Cawley) — Tue, 05 Dec 2006 11:07:00 -0600

My dad drives a vintage Fraser Nash. I say drives, but that’s only half the battle, a large part of his Nash time is spent fettling it. It’s an old car; bits wear out, break or drop off. And because it’s an old car, you can’t just nip round to Halfords and pic up a replacement; nor can you head down to the breaker’s yard and cannibalize something else. So he has a lathe and a milling machine and a bewildering collection of tools. When he needs a part, he will disappear into the machine shop and, after sufficient swearing and/or bleeding, he will emerge with a newly made part. For dad, it’s all part of the fun of running a vintage car. If he weren’t able to do the work, the Nash would have had to remain a pleasant pipedream.

I don’t know my way around a machine shop, except in the vaguest and most theoretical way. The tools I’ve grown up knowing to use are programming languages, editors, fine manuals and the mental tools a grounding in mathematics brings.

So, when I’m putting a new photography business together, and I realise that a couple of the supporting software tools that I had vaguely assumed ‘should exist’ don’t actually exist, I know that it doesn’t matter. I may not know Cocoa programming yet, but I know programming, so I’m confident that, like dad in his machine shop, I’ll be able to knock something up that does the job.

On reflection, I realised that this is probably a good thing. If I can set up and run the business with a combination of off the shelf software, then it’s trivial for potential competitors to reverse engineer the business and do the same (let’s assume here that the business is a success) and I’m left competing on margin in a service industry. No fun at all.

Being able to make my own tools gives me a competitive edge.

Why aren’t there more tool makers?

Because I’m a programer, I know that if my working environment isn’t habitable, it’s possible to fix it. I carry that approach to working with other capable software – keep typing ‘teh’ when I mean ‘the’? Add a macro, autocorrect rule, snippet or whatever you want to call it to the tool I’m using and wonder if it might be a good idea to implement some kind of central repository for such things so I don’t have to repeat myself with every new tool.

The tools to do this sort of thing are there; they’ve never been more available, and in many cases they’re not hard to use, but surprisingly few people seem to be using them. Why is that? Why do people put up with annoying software when (often) the fix is only a couple of settings away? Why are programmers so rare?

I wish I knew. Or maybe I don’t – as long as people don’t realise how easy it is to fix/make things, I’ve got an edge.

Taking control of your tools

If you let your tools shape you, then you’re going to be awfully uncomfortable. Make a commitment to at least capture your annoyances with the tools you use most frequently. Make a note of the problems and think about what you wish the software would do and blog about it. Here’s a couple of stories based on some of the things I need to be able to do for my business:

Auto Slideshows

As an onsite picture editor, I need to run a ‘smart’ slideshow on a secondary display while I working on images on the primary display. The slideshow should be based on an Aperture album and should automatically pick up any changes in the underlying album.

Auto crediting

As an onsite picture editor, I need my slideshow to display a credit on any images in the slideshow that weren’t taken by me. If the Credit metadata doesn’t match ‘Piers Cawley’ the string “by ” should be added as a ‘watermark’ to the displayed image.

If you’re a programmer yourself, you’ve just given yourself a nice list of projects to be working on when you have the time. If you’re not, then you’ve just written a useful set of requirements. Tag your post ‘lazyweb’ and if you’re lucky someone might know how to do exactly what you want without having to write a line of code, or someone else might agree that it’s something that needs fixing and actually fix it. If neither of those two happen, well, at least you’ve vented your frustration, and that’s not a bad thing either.

Another Two Cultures

pdcawley@bofh.org.uk (Piers Cawley) — Fri, 02 Sep 2005 16:47:00 -0500

So, I’m temping now, just another admin worker bee for the council. I can’t say that I’ve found my vocation, but it’s certainly an eye opener.

All my adult life, I’ve seen a computer as an amazingly flexible servant. If it doesn’t yet do what I need then it’s possible to program it so that it does. That’s what computers are for after all.

This seems to be rather a long way from the experience of the people I’m working with. For them the relationship is inverted. The servant becomes the master and they have to conform to its way of doing things. Flexibility disappears.

On my first day I spent some time keying in data from feedback forms into a badly designed Access database. I was walked through the process which involved inputting data into the table view. This isn’t necessarily a bad way of doing things, but some columns were supposed to be set to one of five satisfaction levels, and those levels weren’t simply numbers, they were text: “Excellent”, “Good”, “Satisfactory”, “Poor” and “Don’t Know/Not Applicable”. Not fun to type in repeatedly.

So I spent 10 minutes setting up a form complete with combo boxes and other appropriate devices to ensure that the data entered was valid, with the added bonus that data entry through the form was way faster. I estimate that it would have taken me at least half an hour to input the data through the table view, and I wouldn’t have a great deal of confidence about its validity. With the form, I had the data input within 10 minutes of finishing the form. Bear in mind that this is the first time I’ve ever used Access; it just seemed obvious that anything that called itself an end user database would be able to do what I needed.

Before I started the job there were already 200 entries, all apparently input by hand. Nobody had taken the apparently simple step of adding a form to make life easier. (Someone had, but it was a terrible form with an insane tabbing order, and nobody seemed to know about it).

It’s terribly easy for programmers to dismiss non-programmers as stupid, but they’re really not. There’s a schism between users and programmers that’s as fundamental as the divide between C.P. Snow’s Two Cultures

I’ve written, indirectly, about this before, but this is the first time I’ve seen the difference so plainly. Mainstream software like Microsoft Office becomes more and more programmable with every iteration and those features hardly ever get used by end users. And end users are the people who really could benefit from this stuff. They’re the people who know what they need the software to do. The divide tends to mean that programmers implement what’s easy for them rather than what’s Right. So users, unfamiliar with the power of programmability, end up feeling that a bad ‘solution’ has been foisted on them.

Picking another example, there’s a bookings system here. It’s terrible. Things that should easy to do in software end up being done by hand—one obvious example is when you use a canned query to find all of a client’s bookings, the list that gets returned isn’t in date order. If you book a room to someone the system doesn’t check that the room’s available, you have to check by hand first (but that’s a pain, because, as before, the list of bookings for a room aren’t in date order)... By any measure, the software these people are working with is terrible. It’s not as if it’d be hard to fix, simply tweaking a couple of queries would make things noticeably better.

As far as I can tell, the people who use this system never met any of the people who wrote the code. Or maybe they never had a chance to play with what’s possible, so they don’t know that software doesn’t have to be this bad.

The Usual Sermon

As those of you who’ve been reading this blog for a while can probably guess, this is the bit where I point out that Agile methodologies win big in this situation. Development that gets a rough model into the hands of the users and then debugs its way to full functionality through a dialogue between users and developers will end up with a more habitable product.

The real power of the conversational approach is the conversation itself. If I can get immediate clarification from the user; if my development practice means that I can say “I think I’ve got an idea that’ll make this easy for you, give me half and hour and have a demo for you”; if I can then deliver running code that shows what I mean, then that can only be a win.

It might take a little more time (the Agile people will tell you it’s actually faster because you don’t waste time on unnecessary code and endless meetings and requirements gathering—I tend to believe them) but I’m prepared to bet that the resulting code will be a great deal more robust and useful. Not just that, but the users will have learned an important lesson about the flexibility of code, which just has to be a good thing. Even if users never learn to program themselves, the knowledge of exactly how flexible these tools are is empowering all by itself.

I’m not sure I’d go so far as to recommend that every programmer out there goes and spends some time working in an office doing the daily admin grind, but if you do find yourself in that position, keep your eyes, ears and mind open. There’s a great deal of good stuff to learn—who knows, you might just come up with the next great product.

The Quality Without A Name

pdcawley@bofh.org.uk (Piers Cawley) — Tue, 29 Jul 2003 06:06:00 -0500

The Quality Without A Name is a phrase coined by Christopher Alexander in The Timeless Way of Building to describe the feeling of satisfaction and contentment engendered by good building. He later went on to call it ‘life’, but a friend of mine described it as ‘The Tao of Building’, which seems rather appropriate too. The Timeless Way of Building is a fantastic, if somewhat overwritten book, introducing Alexander’s themes and ideas about how modern architects and builders can recapture the qualities inherent in great (usually old) buildings.

Alexander later went on to crystallize his ideas about how to lay out cities, towns, neighbourhoods, houses, rooms, windows, etc in his massively influential book, A Pattern Language, in which Alexander and his co-authors attempted to set down a ‘language’ that would enable anyone to design and build somewhere that possessed the Quality Without a Name for themselves. Sadly, as they admit later, they failed in this attempt; efforts to use this pattern language by laymen resulted in interesting, but flawed buildings. Despite the failure (in Alexander’s terms) it’s a great book; the prose can be a little annoying at times, but the analysis is deep, and mind-changing. Here’s an extract from one of the patterns:

208. Gradual Stiffening

The Fundamental philosophy behind the use of pattern languages in buildings is that buildings should be uniquely adapted to individual needs and sites; and that the plans of buildings should be rather loose and fluid, in order to accommodate these subtleties.

[An essay describing the problem more fully, and the reasoning behind the solution presented]

Therefore:

Recognize that you are not assembling a building from components like an erector set, but that you are instead weaving a structure which starts out globally complete, but flimsy; then gradually making it stiffer buit still rather flimsy; and only finally making it completely stiff and strong. We believe that in our own time, the most natural version of this process is to put up a shell of sheet materials, and then to make it fully strong by filling it with compressive fill.

Look, Agile Building!

Alexander and his co-writers have found a remarkably powerful way of managing complexity by isolating parts of the process of building in individual patterns, but neatly tying them into the greater whole by their use of introductory and closing paragraphs to explain the context in which a pattern is used. When I read it, I find I’m constantly flipping back and forth to look at these contextual patterns that support (or use) the pattern that I’m concentrating on. The book itself has the Quality Without a Name.

It was only after I’d read The Timeless Way and A Pattern Language that I came across the idea of Design Patterns in programming (In fact, I was working as a contractor and had a copy of The Timeless Way on my desk when a coworker spotted it and made a remark along the lines of “Ah, going back to the source eh?”, which he then had to explain as I didn’t know what he was talking about.) when a friend lent me the Gang of Four’s Design Patterns.

I don’t really like Design Patterns. Too many of the patterns seem to be concerned with working around problems with the static nature of C++ and Java—not exactly useful if you’re used to a more dynamic OO language. Another, deeper failing, is the disjointed nature of the patterns presented; there’s no attempt to tie the patterns together in a coherent language and the whole thing feels like a mishmash of ideas waiting to be turned into a finished book.

There is one software patterns book I’ve read that gets it though, that has The Quality Without A Name in the same way that A Pattern Language does. That book is Smalltalk Best Practice Patterns by Kent Beck. If you don’t know Smalltalk, don’t be put off by that title; a very sizable fraction of the book can be applied directly to any suitably dynamic OO language (Perl, Python, Perl 6, Javascript…) and the syntax of Smalltalk is virtually nonexistent and easy enough to pick up.

The book works well because Beck, quite deliberately, limits its scope to the tactics of coding. Instead of going for the big things, we’re dealing with the nuts and bolts: how to choose good names, how to write methods in ways that encourage reuse and flexibility, how to keep things loosely coupled. Beck explains this stuff with concrete examples and simple rules, that work phenomenally well together. It’s hard to put my finger on why it works so well, but my gut feeling is that it’s because Beck has not forgotten the importance of context.

Very few of the patterns are strictly standalone, they refer to each other up and down the ‘levels’ of the various patterns and the individual patterns are small enough, and well enough supported by the other patterns in the language that they remain tightly focussed on the issue they address.

Smalltalk Best Practice Patterns is a complete pattern language, something that I’ve not seen achieved in any other software patterns book (though Martin Fowler’s Refactoring: Improving the Design of Existing Code gets pretty close.) It’s easy to read; full of practical wisdom from someone who knows their stuff and can explain it well.

I recommend this book wholeheartedly to anyone who wants to become a better programmer, and especially to anyone who does object oriented programming in a dynamic language of any kind. If you find me in a bar amongst programmers, and we’re talking about how to get better at our craft, then I’ll almost certainly be banging on about how good this book is.

I believe the Java types are fans too, but if I were a java programmer then I’d find the kind of flexibility inherent in Smalltalk as expressed in this book would just make me want to abandon Java in favour of something more expressive.