Enumeration conventions

[pixelzoom]

Proposal for Enumeration conventions:

1. Enumerations are named like classes/types. Nothing in the name needs to identify that they are Enumerations. Example:

Orientation, not OrientationEum or OrientatonEnumeration.

2. Enumeration values are named like constants. Example:

new Enumeration( 'HORIZONTAL', 'VERTICAL' ).

3. If an Enumeration is closely related to some class, then make it a static field of that class. Example:

// Definition in Layout.js
LayoutBox.Orientation = new Enumeration( [ 'HORIZONTAL', 'VERTICAL' );

// Use in client
const myLayoutBox = new LayoutBox( ..., {
  orientation: LayoutBox.Orientation.HORIZONTAL
} );

4. If an Enumeration is not closely related to some class, then put the Enumeration in its own .js file. Do not combine multiple Enumerations into one file. Example:

// Justification.js

define( require => {
  'use strict';

  // modules
  const Enumeration = require( 'PHET_CORE/Enumeration' );
  const someNamespace = require( ... );

  const Justification = new Enumeration( [ 'LEFT', 'RIGHT', 'CENTER' ] );

  return someNamespace.register( 'Justification', Justification );
} );

5. As with other sim code, put Enumeration .js files in the subdirectory that they are related to.

[pixelzoom]

Some "rules of thumb" for deciding where to put an Enumeration:

• If an Enumeration is used for a specific Property, put the Enumeration definition with the class that owns that Property. Example:

// MyModel.js

class MyModel {
  constructor() {
    // @public - the speed at which the simulation is playing
    this.playSpeedProperty = new Property( MyModel.PlaySpeed.NORMAL, {
      validValues: MyModel.PlaySpeed.VALUES
    } );
    ...
  }
}

MyModel.PlaySpeed = new Enumeration( [ 'NORMAL', 'FAST', 'SLOW' ] ); 

• If an Enumeration is used by Properties owned by 2 or more classes, then the Enumeration should probably be in its own .js file.

• If an Enumeration is related to a specific view component, then the Enumeration should probably be associated with that view component. Example:

// LayoutBox.js

class LayoutBox extends ... {
  constructor(..., options ) {
    options = _.extend( {
      orientation: LayoutBox.Orientation.HORIZONTAL
      ...
    }, options );
    ...
  }
}

LayoutBox.Orientation = new Enumeration( 'HORIZONTAL', 'VERTICAL' );

// client use

const layoutBox = new LayoutBox( ..., {
  orientation: LayoutBox.Orientation.VERTICAL
  ...
} );

[pixelzoom]

1/10/19 dev meeting:

Wave Interference and Gas Properties currently use the above proposal.

Consensus is that this proposal is close enough to add to phet-software-design-patterns.md, which I'll do in phetsims/phet-info#88.

[pixelzoom]

Another convention related to Enumeration:

(5) If a Property takes an Enumeration value, its validation typically looks like this:

     const cardinalDirectionProperty = new Property( CardinalDirection.NORTH, {
       validValues: CardinalDirection.VALUES
     } 

[pixelzoom]

Conventions have been moved to the header comment of Enumeration.js, and are referred to in phet-software-design-patterns.md.

Closing.