The XtC, haikus and comments

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.

This entry was posted in Uncategorized. Bookmark the permalink.

7 Responses to The XtC, haikus and comments

  1. anonymous says:

    Another virtue of haiku is that it’s short. Wordy comments indicate that your could say what you want through code better.

    Consider:

    /**
    * Move the shape as told.
    *
    * @return false – move not allowed
    *
    * No Direction.DROP
    */
    public boolean move(Direction direction) {
    assert direction != Direction.DROP : “Don’t pass DROP to move”;

    }

    Direction, of course, lists the permitted directions as enums.

    (I know, you weren’t _really_ asking for comments in haiku form 😉

  2. sirenian says:

    Mmm. To me, the “move” method name covers “Move the shape as told”, it’s easy to guess the purpose of the boolean return, and “No Direction.DROP” doesn’t actually tell you what you are allowed. It therefore lacks the surprise element which is crucial to all the best haikus.

    May I venture:

    /**
    * Shape type changes moves. (this is what the “rotated positions” does)
    * Detritus / edge block attempts.
    * Turn or shift – don’t drop.
    */

  3. entropyjim says:

    The second comment strikes me as a comment put in place because someone was under pressure to finish something. Many comments get put in place in a rush, or with the intention that they will be spruced up later.

    In an ideal environment all coders will have the time to fully test and comment their code. We don’t live in an ideal world 😉

  4. sirenian says:

    I get mostly tested code now. It’s a big improvement!

  5. boryon says:

    Tested code? What’s that?

    I would put a smilie here, but…

    Chris

  6. anonymous says:

    I don’t think that duplicating ‘obvious’ code with a comment that reflects exactly that is bad at all.

    Just because you *think* you’ve written some code that does exactly what you want, doesn’t mean that it does. If you explain and verify your code with English words then someone better can improve it for you later.

  7. sirenian says:

    Sure, but if you’re using behaviour / test driven development then your code always does exactly what you want, because you wrote the tests for the behaviour you wanted before you wrote the code. If my tests and methods are well-named, then the comments are superfluous, and if they aren’t then I think I need to start there before I start wasting time on code comments.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s