Java By Comparison

Document Implementation Decisions

class Inventory {

    private List<Supply> list = new ArrayList<>();

    void add(Supply supply) {
        list.add(supply);
        Collections.sort(list);
    }

    boolean isInStock(String name) {
        // fast implementation
        return Collections.binarySearch(list, new Supply(name)) != -1;
    }
}

Decisions are what make life hard. They do the same to code.

Sometimes you have to make a hard decision in your code—one where there’s no objective right or wrong, one that has advantages and disadvantages. This is when you need comments!

Consider the code above. Are you wondering why the programmer decided to use a binarySearch? Well, at least he left us a (helpful) comment: it has to be fast.

The programmer made ...