Include preferred coding patterns somewhere in the documentation

[AgustinVallejo]

As part of phetsims/models-of-the-hydrogen-atom#125 I was discussing with @pixelzoom about the following conventions for exposing fields:

  public readonly positionProperty: TReadOnlyProperty<Vector2>;
  private readonly _positionProperty: Property<Vector2>;

To avoid clients or outside classes from modifying private fields. I realized this is not a pattern I really use in my sims and was wondering if it'd be worth promoting into our convention documentation, as others might be unaware of these details.

[pixelzoom]

This pattern concerns the situation where a field (often a Property) is read-only for the public API, but writeable internally to the class. Two common implementation patterns are shown below. @AgustinVallejo was commenting on the first pattern, which is used in MOTHA. The anti-pattern shown below is unfortunately what I see too often in code reviews.

// Pattern 1: This pattern uses 2 references to the same Property instance. The public reference 
// is read-only for getting the value. The private reference is for setting and resetting the instance
// internal to the class.
class MyClass {

  public readonly positionProperty: TReadOnlyProperty<Vector2>;
  private readonly _positionProperty: Property<Vector2>;

  public constructor() {
     this. _positionProperty = new Vector2Property( ... );
     this. positionProperty = this.positionProperty;
  }

  public reset(): void {
    this._positionProperty.reset();
  }
}

// Pattern 2: This pattern uses 1 private reference to the Property instance and 
// a public ES5 getter.
class MyClass {

  private readonly positionProperty: Property<Vector2>;

  public constructor() {
     this. positionProperty = new Vector2Property( ... );
  }

  public reset(): void {
    this.positionProperty.reset();
  }

  get position(): Vector2 {
    return this.positionProperty.value;
  }
}

// Anti-pattern:  A single reference that is writeable in the public API, with documentation 
// saying "don't write to this", or an implicit hope that no one will write to it.
class MyClass {

  public readonly positionProperty: Property<Vector2>;

  public constructor() {
     this. positionProperty = new Vector2Property( ... );
  }

  public reset(): void {
    this.positionProperty.reset();
  }
}