Comments considered harmful

At school, I was taught to comment my programs well. Today, I wonder why I should.

Every comment relating to the code itself is redundant. Redundancy creates inconsistencies, and inconsistencies are a serious threat to code quality. So I prefer not to comment.

"Hey, come on! How do you expect anybody to understand your program if you don't comment it?" I hear being shouted at me. I will ask the opposite question: Why should I write such a lousy program that it needs comments to be understood?

I worked in a group where the coding guidelines said: Comment every class, comment every method. I refused. I mean, as an example, look at this getter, generated by the Refactor -> Encapsulate Fields... operation of NetBeans:

    private String name;
    /**
     * @return the name
     */
    public String getName() {
        return name;
    }

What does that comment add that I did not already learn from the method name? So rather than commenting a method, I prefer to use the comment,  kind of, as the method name. That guarantees consistency and also propagates the "commented" intent to every place the method name is referred to. Far superior to a localized comment!

Martin Fowler once said: "Any fool can write code that a computer can understand. Good programmers write code that humans can understand." I strive to be one of them.

Iterations and increments iterated

It seems hard to get this right. Jeff Patton uses Mona Lisa to explain it. Alistair Cockburn uses Michelangelo and van Bruegel the elder, stating that "Incremental means adding, iterative means reworking" (my emphasis). That would be in the product dimension. Thomas Nilsson, in a Swedish agile forum, writes "In my world, incremental relates to the product dimension, whereas iterative relates to the process dimension" (my emphasis).

To summarize, I find it helpful to consider iterations and increments in both of these dimensions.

• An iterative process would be like any agile process. You repeat the same development activities over and over. That's what we like to do.
• An iteration in the product dimension would be, as Cockburn points out, improving quality or functionality of the product. That is certainly legitimate in a lot of situations. You make a tentative solution — not necessarily a prototype — and you present it. It may be accepted or rejected. But even if accepted, the customer may want to iterate on it to improve it. Tom Gilb calls it evolutionary development. And we may want to iterate on it, refactor it, to improve its internal quality.
• An increment in the process would imply doing more and more things in each iteration, like documenting more, testing more, designing more, or even adding new steps. This happens in many situations where thing go wrong. Then you add rules or steps to go through to prevent that from happening again. Isn't that how heavy processes emerge?
• Incrementing the product would be adding new features to it. That's what we normally do.

All of this may be summarized in a small table.

Is this distinction helpful? Well, I think it is always helpful to understand the words you are using.

So, within the framework of an iterative process, we both iterate on the product and we increment the product.

Does all of this assume an iterative process in the first place? I don't think so. Look at a typical waterfall development process. While deployment may be neither iterative nor incremental, I am sure that in most cases the development is de facto incremental, despite the linear process. The developers are even likely to iterate over the (still undeployed) product. So the product is developed both iteratively and incrementally. But the process is not iterative.

And I find that in RUP, for instance, the process is iterative, and you are supposed to build the product incrementally. But RUP does not encourage iterating on the product itself. To me, that's one important factor that makes it very waterfallish and inapt to adaptive development.

To implement the agile values, the process needs to be iterative, and you need to both iterate on the product and increment the product during your process iterations. Waterfall fails in not being an iterative process. RUP fails in not iterating on the product.

The Agile Team Room

During a recent training course, we discussed the agile team room, especially the whiteboard space for modelling. Fortunately, Mike Cohn just published a blog, listing the essential features for The Ideal Agile Workspace:

• Big Visible Charts
• Additional feedback devices
• Everyone on your team
• The sprint backlog
• The product backlog
• At least one big white board
• Someplace quiet and private
• Food and drink, and finally
• A window
  

The comments link to several implementations of this list. For instance, one of the comments link to a tour through the msdn Patterns and Practices Lab and a peek inside the p&p Team Room. Of course, these are quite advanced implementations of Mike's list, but show how important these companies find the physical environment.

DCI, or restoring order to OO

Object orientation (OO) is often contrasted with structured programming (SP). OO has many advantages when it comes to managing complexity, but it clearly lacks in exposing clairly what the code is actually achieving. SP on the other hand has many defeciencies when it comes to separation of concerns and maintainability, but at least it is normally possible to follow the execution sequence in the code.

In my OO training courses, I frequently warn the attendees, saying that OO may solve the problem of complexity and changeability, but requires another level of competence to maintain clarity and overall understandability. A lack of this competence may produce a spaghetti code that is an order of magnitude worse that the traditional, structured spaghetti code. Please be warned!

Enters Professor Trygve Reenskaug, the principal inventor of the MVC paradigm, with a new DCI paradigm, supported by Jim Coplien. As I understand it, DCI is complementing OO and MVC, supplying the overall interaction scheme, showing how the individual objects, based on their roles, collaborate to deliver business value: It supplies a role based expression of the communication logic, like in sequence or communication diagrams.

I have to look closer into the material, for instance how DCI expresses the communication scheme better than e.g. communication digrams, but it does look interesting.

… but please do repeat me

Do you have to choose duplication, paralysis, or chaos?

Johannes Brodwall wrote a blog with this title on a subject that has interested me for a long time: How to avoid chaos and support stability in face of a constantly changing interface (my rephrasing). He sketches three different approaches:

1. Duplicate code, so that change at one place does not affect code somewhere else, but at the cost of duplicated changes of common logic
   
2. Share code, to avoid duplicated changes of common logic, but at the cost of requiring change in all the clients when the logic of any of the suppliers changes
3. Do not allow changes, to avoid both of the inconveniences above, but at the cost of conserving unsatisfactory solutions

I tend to think that the solution will change over time.

• Initial code is unstable and has only a few clients. Apply approach 2.
  
• As code matures and stabilizes, fix its contract (precondition and postcondition). Apply rule 3 and the open/closed principle.
  
• A subsequent change may of may not break the contract.

1. If it does not (weaker precondtion, stronger postcondition), there is nothing to worry about - clients are not affected by the change. All tests will pass unchanged.
   
2. If it does, apply rule 1 and define a new function for the new contract, possibly making the old definition deprecated to leave a transision time for the clients.

User Story Mapping

A lightening talk by Nils Christian Haugen (in Norwegian) on Smidig2008 (Norwegian Agile2008) was on User Story Mapping, as proposed by Jeff Patton. The user stories need a context, which shows how they generate value to the organization. So you have user roles, user activities and user tasks, which may be broken down into user stories.

Isn't this reinventing the Business Use Cases? Perhaps, perhaps not. I think it conveys the same idea, but I find the presentation an interesting layout of Use Case actors, more intuitive and easier to transfer to clients and developers alike. So I like it. Besides, they are devoid of the undeserved bad reputation of Use Cases as being written in stone.

What about epics? Aren't epics the same thing? Well, an epic is like a user story too big to be implemented in one iteration. But once you start implementing it, what then? You probably don't finish it all during one sprint, so it needs to remain, at the same time as parts of it appear as user stories. That creates kind of double messages, since they belong to different levels of description, and this leveling is not captured by the User Story technique. I think Use Case scenarios, Quantified Qualities à la Tom Gilb or User Story Map tasks capture this effect better. They also provide a framework for keeping the big picture in view and assuring that the user stories you pick support each other, and that together they make up a profitable user activity, or Business Scenario.

You may also ask whether this oveall, business level description belongs to the development team. Isn't that the Product Owner's table? I think experience shows that the Product Owner has a hard time setting up and maintaining this kind of plans on his own, and that it is extremely beneficial, if not mandatory, for the team to gain this overall level of understanding. So yes, I think it belongs to the team and serves well to support sprint and release planning as a complement to user stories.

Is software development an art?

In a recent blogg, MissUnderstodd asks the above question. I have noted that artists go to several years of education before. They learn a lot of techniques, aestetics, mechanisms and so on, so they know that to obtain a certain effect, they need to proceed in a certain way.

So do software developers. So yes, I think software development is comparable to the work of an artist. You know what you want to obtain, you know the rules for getting there and there is a lot of freedom for artistic work in between.