This is a guest post from Håkan Rudelius. I’ve been working with Håkan for the last few months at Com Hem (Sweden’s major cable operator) and the discussions with him have been a great inspiration for me on agile, lean and team building.

A friend of mine, Jan, who is consulting at a major telecom company came up with a real nifty idea for how to make documenting smooth and well, almost – fun…
You recall how it’s normally done, right? One poor team member has to “volunteer” to the far from glorious mission of updating the system documentation to reflect the system updates that the team made in the sprint. So the poor guy has to write down everything he knows and then walk around and interview the rest of the team to get everything right. This task normally takes longer than expected because:

1. It’s so boring so you take every opportunity to get distracted.
   You go get yet another cup of coffee.
   You join a discussion between fellow developers.
   You check that interesting website about nhibernate.
   And so on
   

2. The person you need to interview is busy.

Once the document is updated, you normally have to have at least one boring review meeting to get everything right.

So in order to get around these problems my friend decided to try “team documenting” or “mob documenting”.

• Continue Reading →

Having up to date and relevant documentation is a challenge for any software maintenance team. The key to success is to write a minimum of documentation, but make sure that it is relevant. The details can always be sorted out from the code. The external documentation (that is not in the code) should focus on being a good introduction by giving an overview.

The documentation should point in the right direction to get started working with the code base and show what modules there are. It is a bit like when first arriving at a resort. You’d expect a map and some directional signs to use until you’ve got to know your way around the area.

Before going into how it looks like, let’s consider how it would be if the resort was documented the way most code is.

The instructions where clear: “Drive 24.7 km on the main road north, then take off to the right”.

The trip meter now is on 24.7 km. It is dark. No street lights to be seen anywhere close. No signs. No road to the right. Nothing but a trail of mud and sand between the dark trees. Well this is where it should be, so you take to the right.

The ride is bumpy but it is clear that cars regularly drive here. Suddenly the mud and sand is replace by a proper concrete road. The forest leaves place for a beautiful view of the large, luxurious resort close to a moonlit lake. You park the car among the other cars (although there is no parking sign, but it must be here) and head off towards the main building.

You find a closed door. There is a well used path in the grass around the corner so you follow it, just to end up on a small beach, still carrying your luggage. Going back you see a door which is open and head over there. It is the restaurant, but at least you find a waiter that can show you the way to the reception.

The receptionist is nice and your check in is processed quickly. You get the keys and head over to the elevator. Once inside you check for the right floor for your room number which is: D7BC. There is no D on the panel. Just plain numbers 1-15. Before you can decide what to do the elevator moves on to floor 7 where a family is waiting to get in the elevator. You get off to leave room and have time to think.

Think this is ridiculous? Unfortunately this is the very same feeling that I far too often get when first looking at a new code base. I’m not finished yet, there’s more to come…

• Continue Reading →

A true master craftsman of any profession takes pride in doing a great work. A masterpiece is recognized by the combination of a great total impression and worked out details. Most programmers tend to think that their latest code is a masterpiece. I even went as far as starting this blog, to show off all the masterpieces of code I write ;-).

The sad truth is that looking thoroughly at some code it’s often far from the carefully worked out details of a true master piece. Let’s look at an example of how code can look and try to get it right (according to my definition of right).

public class Car
{
        [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Naming", "CA1709:IdentifiersShouldBeCasedCorrectly", MessageId = "reg")]
        public string regNo { get; set; }
    public string Brand { get; set; }
 
    /// <summary>
    /// Drive the car
    /// </summary>
    /// <param name="speed">Speed to drive at</param>
    public void Drive()
    {
        Debug.WriteLine("Driving car!");
    }
 
    public void DragRace(DragStrip strip)
    {
        while (!strip.AtEnd)
        {
            try
            {
                Drive();
            }
            catch (Exception) { }
        }
    }
}

This is not real code from a project (if it was, I would need stress therapy), but I’ve seen all of these examples in live code. If I found this during code review, there would be a number of things I would point out.

• Continue Reading →