Being a good commentator

When i grew up writing code I love comments. Whatever comments they were, I just love them. Single line comments, Multi-line comments that describe what each line of code does to javadoc comments.

Number of years ago, I used to write javadocs like this:

/**
 * Gets the subtotal
 * 
 * @return the subTotal
 */
public BigDecimal getSubTotal() {
       return subTotal;
}

And this…

/**
 * Puts an item into the basket
 * 
 * If there is already the same item in basket then increment the 
 * quantity number
 * 
 * @param item to put in basket
 */
public void putItemInBasket(BasketItem newItem){

Also this…….

/**
 * Calculates the total of the items of goods.
 * This takes into account of the special offers in place and applies
 * the special offers which is then subtracted from the subtotal
 * 
 * @return the total (after special offer deductions) 
 */
public abstract void calculateTotal();

I’d write single line comments explaining line of code of what it does or what the following code’s intentions are:

// bought enough items to satisfy special offer
if (quantity >= 2) {

       // special offer applied, bought item at half price
       if (basketOfItems.basketContainItem(halfPriceItem)) {