fill in gaps in public-facing developer documentation

[pixelzoom]

Over in phetsims/normal-modes#2, I did a code review of Normal Modes, contributed by a 3rd party. The review took longer than expected because the 3rd party was not aware of some of the essential tools and documentation that PhET relies on.

@ariel-phet asked me to create this issue based on my comment in phetsims/normal-modes#2 (comment):

Most of the deficiencies (e.g. lint, assertions) can be traced to deficiencies in PHET's documentation for 3rd-party developers. @ariel-phet we might consider triaging these GitHub issues to pull out the things that need to be improved in PhET doc.

In the case of Normal Modes, the 3rd party was not aware of:

• assertions
• lint
• PhET Software Design Patterns doc (especially options pattern)

Looking through the GitHub issues related to the code review may identify some others, but those are the "big 3".

[samreid]

If assert was an import instead of a global, then users could have a clear path to navigating to it, then we can document it there?

[zepumph]

From developer meeting today:

• Not a super high priority
• There are more developers out there using our code
• Updating documentation is important
  • Running lint
  • enabled assertions (maybe we enabled by default)
  • Using es6 modules
• Add assertions to example-sim/simula rasa as examples (there are none currently)

@pixelzoom volunteered to implement the last two bullets. Thank you @pixelzoom!!

[pixelzoom]

• Running lint

I added this to the "Utilities and Instrumentation for Development and Testing" section of the PhET Development Overview:

12. Run grunt lint on the command line to check for lint errors. All code should be free of lint errors. (lint is a tool that analyzes source code to flag programming errors, bugs, stylistic errors, and suspicious constructs. PhET uses the eslint variant of lint.)

• enabled assertions (maybe we enabled by default)

There was a sparse description of ?ea in "Utilities and Instrumentation for Development and Testing" section of the PhET Development Overview. I revised it to read:

3. Run with query parameter ?ea to enable assertions in the code. The sim should run without any assertion errors. (Assertions are predicates about what should be true at specific points in the code. They are used to identify programming errors.)

• Using es6 modules

This will presumably be addressed by phetsims/chipper#854, no action required here.

• Add assertions to example-sim/simula rasa as examples (there are none currently)

I added assertions that type-check arguments to example-sim and simula-rasa. The example in example-sim explains what they are, and how to enable them:

    // This is an example of using assertions to check for potential programming errors. In this case, we are verifying
    // that the arguments have the expected type.  Run the simulation with query parameter ?ea to enable assertions.
    assert && assert( barMagnet instanceof BarMagnet, 'invalid barMagnet' );
    assert && assert( modelViewTransform instanceof ModelViewTransform2, 'invalid modelViewTransform' );

@ariel-phet please assigning someone to review.

[ariel-phet]

@chrisklus please feel free to close once review (and any changes or back and forth that should take place) are complete.

[chrisklus]

Code and documentation changes look good. I tested the type checks added to simula-rasa with grunt create-sim and they're working as expected. Thanks @pixelzoom, back to you to close if all set.

[pixelzoom]

👍 Closing.