Document for Concurrency

class Counter {

  private long count;

  synchronized void increment(long amount) {
    if (amount < 1) {
      throw new IllegalArgumentException("Only increments!");
    }

    this.count += amount;
  }
}

Knowing if a method is thread safe is very important!
Without documentation, it takes some time to figure out if it really is thread-safe


/** thread safe */
class Counter {

  /** guarded by 'this' */
  private long count;

  synchronized void increment(long amount) {
    if (amount < 1) {
      throw new IllegalArgumentException("Only increments!");
    }

    this.count += amount;
  }
}

comments similar to the annotations from Java Concurrency in Practice
help to safely use the classes
multiple variants: thread-safe, immutable, conditionally thread-safe, not thread-safe