Comments and Style

Here's a small fragment I've just spotted in The Elements of Java Style.

if (this.invoiceTotal > 1000.0) {
    this.invoiceTotal = this.invoiceTotal * 0.95;
}

The authors say that the program appears to give a 5 percent discount. And again in the comment (the tip is on writing comments) they point out that:

// Apply a 5% discount to all invoices 
// over one thousand dollars

is a valueless comment because it provides little additional information. Maybe. But it does provide some additional information. I count three things the comment says that the code doesn't. One is the % symbol, two is the word discount, and three is the word dollars. The point is you can say these three things in the software itself. For example:

if (this.invoiceTotal > 1000.0) {
    final double discount = this.invoiceTotal * 0.05;
    this.invoiceTotal = this.invoiceTotal - discount;
}

To my eyes the repetitive this. is just noise, so I would simplify to:

if (invoiceTotal > 1000.0) {
    final double discount = invoiceTotal * 0.05;
    invoiceTotal = invoiceTotal - discount;
}

and then to:

if (invoiceTotal > 1000.0) {
    final double discount = invoiceTotal * 0.05;
    invoiceTotal -= discount;
}

Say it in software. Less code, more software.

I've received some feedback on my initial post - which is nice. Ric Parkin advised caution about drawing analogies from The Quantum Self - mostly because any analogy, when stretched too far, will snap. And I agree. Analogies can be useful but you musn't forget that software is a discipline in its own right.

So to expound a little, when I was thinking of the particle/wave analogy I wasn't thinking of the dynamic aspect, the interaction - I was likening the particle aspect to the inside of an entity and the wave aspect to its connections to the outside. The shape. The fractal shape if you like (since I'm also reading Chaos). Shape is important. Richard Gabriel talks about shape quite a lot in his excellent book Patterns of Software.

Kevlin Henny (who incidentally, coined the phrase "less code more software") also had some insightful comments on the word follows in "form follows forces". It suggests moving only in one direction, and we all know this is not the case. Developing software is not a linear process. Feedback is natural and healthy. If there was a word that conveyed follows-and-is-followed-by I'd use that. But I can't think of one.