Last night I went to the XtC, where I met a bunch of very interesting people and discussed best coding practices and haiku.

We decided that while it would be lovely to see comments in haiku-esque form throughout code, to break up the flow of all those strange lines more than anything, it would eventually become distracting and annoying. It got me to thinking, though, about the nature of haiku and the purpose of comments. These thoughts were mostly spurred by Nat‘s article on comments yesterday.

Most people make the mistake of defining haiku as “a poem with five syllables in the first line, seven in the second and five in the third”. The syllables are only really relevant if you’re writing in Japanese. It’s much more important when writing haiku that it should capture a moment in time, giving some unique insight into an everyday event. Normally haikus contain a “kigo”, or seasonal word, to indicate what time of year it is.

Another rule which I’ve heard is that the first line of a haiku should be immediate, something related to the writer. The second should be something more abstract, placing the poem in context. The third should deliver the surprising insight or twist. It struck me that this would in fact be a very good way to flavour three-part comments. The first part should be immediate and tell you why the code section is the way it is. The second should relate the code section to the rest of the system. The third part should deliver an insight which cannot be seen simply by looking at the method signature.

This means that the comment below (from my “Hellbound” variant of Tetris):

public void AbstractShape implements Shape {

    ...

    /**
     * Uses the rotated positions of the shape to determine how it responds
     * to movement.
     *
     * @param movement one of LEFT, RIGHT, DOWN, ROTATE_RIGHT or
     * ROTATE_LEFT. Do not pass the DROP event to this method - break
     * it into separate DOWN events until blocked instead
     *
     * @return true if the shape moves successfully, false if the detritus*
     * or the edges of the board block a move
     */
    public boolean move(String movement) {
        ...
    }

    protected abstract Point[] getRotatedPositions(int newQuarterTurns);
}

*the pile of dead shapes at the bottom of the board

is a haiku-esque comment, whereas this one:

public void AbstractShape implements Shape {

    ...

    /**
     * Moves this shape.
     * @param movement the movement which this shape should attempt
     * @return true if successful, false otherwise
     */
    public boolean move(String movement) {
        ...
    }
}

although shorter, is not.

The first comment tells me things that I didn’t know and ensures that any shapes I code which override this method adhere to a specified contract. It also tells users of the method what they can and can’t do with it (the can’t is more important, as it won’t be covered by tests). It tells me why the method behaves the way it does. It doesn’t tell me what the method does, as that’s covered by the method name and additionally by the tests.

The second comment doesn’t tell me anything which I didn’t know already.

It’s a terrible idea to include extra syllables in a haiku just so that it matches up to some preconceived notion of what a haiku should be. It’s also a terrible idea to include comments just because some strange style checker / team leader insists that you have to have them. A haiku should deliver a surprising insight in as short a space as possible. A comment should do the same. (Thanks, Nat!)

So. Time to go through the bits of code which I wrote before my recent enlightenment, and ensure that the comments are either beautiful or absent. I may need to do something similar with my poetry collection.