2 Replies Latest reply on Nov 11, 2010 3:44 PM by David Lloyd

    Please javadoc concurrency semantics

    Jason Greene Master

      Since more and more people are starting to work on the code base, we really need to be clear about what the concurrency semantics are for every class. It just takes a few extra minutes and will likely save hours of time by preventing unintentional breakage, and preventing others from having to infer it.


      All I ask, is that on every new class you do just add a simple Thread-Safety like section, and explain how you intend the class to be used. Also if you modify a class please make sure your modification either fits the previously documented semantics, or carefully explore the consequences when you change them. This will also help tip-off reviewers that such a change is happening.


      In many cases this could be just one sentence:


      "Thread-Safety: This class is not thread safe, and is intended to have an instance per thread"


      "Thread-Safety: This class is not thread safe, and is intended to have all interactions guarded by a lock"


      "Thread-Safety: This class allows concurrent access to any method, but needs a happens-before event between construction and usage"


      Of course more complex designs would need additional information, however typing that out will probably make you think through it a little more, and you may catch flaws you didn't originally think of. I know I have before.