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.