code review

[pixelzoom]

PhET code-review checklist

Build and Run Checks

• [x] Does the sim build without warnings or errors?
• [x] Does the sim start up? (requirejs and built versions)
• [x] Does the sim experience any assertion failures? (run with query parameter 'ea')
• [x] Does the sim pass a scenery fuzzer test? (run with query parameter 'fuzzMouse&ea')

Internationalization

• [x] Are there any strings that are not being internationalized? (run with query parameter 'stringTest=x', you should see nothing but 'x' strings)
• [x] Does the sim layout gracefully handle internationalized strings that are twice as long as the English strings? (run with query parameter 'stringTest=double')
• [x] Does the sim layout gracefully handle internationalized strings that are exceptionally long? (run with query parameter 'stringTest=long')
• [x] Does the sim layout gracefully handle internationalized strings that are shorter than the English strings? (run with query parameter 'stringTest=X')
• [x] Does the sim stay on the sim page (doesn't redirect to an external page) when running with the query parameter 'stringTest=xss' (test passes if sim does not redirect, OK if sim crashes or fails to fully start). Only test on one desktop platform.
• [x] Make sure the string keys are all perfect, they are difficult to change after 1.0.0 is published. Strings keys should generally match the values, such as {binaryProbability: "Binary Probability"}. Screen names should use camelcase, like so screen.screenName. For patterns that contain placeholders (e.g. "My name is {{first}} {{last}}") choose keys that are unlikley to conflict with strings that might be needed in the future. For example, for "{{price}}" consider using key "pricePattern" instead of "price", if you think there might be a future need for a "price" string.

Repository structure

• [x] Are all required files and directories present? For a sim repository named “my-repo”, the general structure should look like this (where assets/, audio/ or images/ may be omitted if the sim doesn’t have those types of assets).

   my-repo/
      assets/
      audio/
         license.json
      doc/
         model.md
         implementation-notes.md
      images/
         license.json
      js/
         (see section below)
      dependencies.json (@samreid thinks this is only necessary in a branch)
      .gitignore
      my-repo_en.html
      my-repo-strings_en.json
      Gruntfile.js
      LICENSE
      package.json
      README.md

For a common-code repository, the structure is similar, but some of the files and directories may not be present if the repo doesn’t have audio, images, strings, or a demo application.

• [x] Is the js/ directory properly structured? All JavaScript source should be in the js/ directory. There should be a subdirectory for each screen (this also applies for single-screen sims, where the subdirectory matches the repo name). For a multi-screen sim, code shared by 2 or more screens should be in a js/common/ subdirectory. Model and view code should be in model/ and view/ subdirectories for each screen and common/. For example, for a sim with screens “Introduction” and “Lab”, the general directory structure should look like this:

   my-repo/
      js/
         common/
            model/
            view/
         introduction/
            model/
            view/
         lab/
            model/
            view/
         my-repo-config.js
         my-repo-main.js
         myRepo.js

• [x] Is there a file in assets/ for every resource file in audio/ and images/? Note that there is not necessarily a 1:1 correspondence between asset and resource files; for example, several images may be in the same .ai file.
• [x] Was the README.md generated by grunt published-README or grunt unpublished-README?
• [x] Does package.json refer to any dependencies that are not used by the sim?
• [x] Does sim-config.js refer to any dependencies that are not used by the sim?
• [x] Is the LICENSE file correct? (GPL v3 for sims, MIT for common code)
• [x] Does .gitignore match the one in simula-rasa?
• [x] Does a GitHub issue exist for tracking credits, to ensure that they are correct before publication?
• [x] Are there git repository branches that are no longer used and should be pruned?

Coding conventions

• [x] Does the code meet PhET's code-style guidelines, as described in the “Coding Style Guidelines” section of the "PhET Development Overview"?
• [x] Is the code formatted according to PhET conventions? See phet-idea-code-style.xml for IntelliJ IDEA code style.
• [x] Are copyright headers present and up to date? Run grunt update-copyright-dates.

Documentation

• [x] Are documentation conventions followed, as described in the “Coding Style Guidelines” section of the PhET Development Overview?
• [x] Does model.md adequately describe the model, in terms appropriate for teachers?
• [x] Does implementation-notes.md adequately describe the implementation, with an overview that will be useful to future maintainers?
• [x] Are sim-specific query parameters (if any) identified and documented in one .js file in js/common/ or js/ (if there is no common/)? The .js file should be named {{REPO}}QueryParameters, for example ArithmeticQueryParameters for the aritmetic repository.
• [x] Do the @author annotations seem correct?

Math Libraries

• [x] Check that dot.Util.roundSymmetric is used instead of Math.round. Math.round does not treat positive and negative numbers symmetrically, see https://github.com/phetsims/dot/issues/35#issuecomment-113587879.
• [x] dot.Util.toFixed or dot.Util.toFixedNumber should be used instead of toFixed. JavaScript's toFixed is notoriously buggy. Behavior differs depending on browser, because the spec doesn't specify whether to round or floor.
• [x] Check that random numbers are generated using phet.joist.random, and are doing so after modules are declared (non-statically). For instance, the following methods (and perhaps others) should not be used:
• Math.random
• _.shuffle
• _.sample
• _.random
• new Random()

Organization, Readability, Maintainability

• [x] Does the organization and structure of the code make sense? Do the model and view contain types that you would expect (or guess!) by looking at the sim? Do the names of things correspond to the names that you see in the user interface?
• [x] Are appropriate design patterns used?
• [x] Is inheritance used where appropriate? Does the type hierarchy make sense?
• [x] Is there any unnecessary coupling? (e.g., by passing large objects to constructors, or exposing unnecessary properties/functions)
• [x] Is there too much unnecessary decoupling? (e.g. by passing all of the properties of an object independently instead of passing the object itself)?
• [x] Are the source files reasonable in size? Scrutinize large files with too many responsibilities - can responsibilities be broken into smaller delegates?
• [x] Are any significant chunks of code duplicated? This will be checked manually as well as with https://github.com/danielstjules/jsinspect
• [x] Is there anything that should be generalized and migrated to common code?
• [x] Are there any TODO or FIXME comments in the code? They should be addressed or promoted to GitHub issues.
• [x] Does the implementation rely on any specific constant values that are likely to change in the future? Identify constants that might be changed in the future. (Use your judgement about which constants are likely candidates.) Does changing the values of these constants break the sim? For example, see https://github.com/phetsims/plinko-probability/issues/84.
• [x] The simulation should use Property instead of PropertySet
• [x] Are all dependent properties modeled as DerivedProperty instead of Property?

Performance, Usability

• [x] Does the sim perform as desired across the range of supported platforms? (eg, not too slow on slow platforms, not too fast on fast platforms)
• [x] If the sim uses WebGL, does it have a fallback? Does the fallback perform reasonably well? (run with query parameter 'webgl=false')
• [x] Are UI components sufficiently responsive? (especially continuous UI components, such as sliders)
• [x] Are pointer areas optimized, especially for touch? (run with query parameter 'showPointerAreas')
• [x] Do pointer areas overlap? (run with query parameter 'showPointerAreas')
• [x] Is the timestep dt capped appropriately? Try switching applications or browser tabs, then switch back. Did the model take one big/long/awkward step forward? If so, dt may need to be capped. Example from faradays-law.FaradaysLawModel:

// Cap large dt values, which can occur when the tab containing
// the sim had been hidden and then re-shown
dt = Math.min( 0.1, dt );

Memory Leaks

• [x] Does a heap comparison using Chrome Developer Tools indicate a memory leak? (Describing this process is beyond the scope of this document.)
• [x] For each common-code component (sun, scenery-phet, vegas, …) that opaquely registers observers or listeners, is there a call to that component’s dispose function, or documentation about why dispose is unnecessary?
• [x] Are there leaks due to registering observers or listeners? These guidelines should be followed, or documentation added about why following them is not necessary:
  • [ ] AXON: Property.link is accompanied by Property.unlink.
  • [ ] AXON: PropertySet.link is accompanied by PropertySet.unlink.
  • [ ] AXON: Creation of DerivedProperty is accompanied by dispose.
  • [ ] AXON: Creation of Multilink is accompanied by dispose.
  • [ ] AXON: Events.on is accompanied by Events.off.
  • [ ] AXON: Emitter.addListener is accompanied by Emitter.removeListener.
  • [ ] SCENERY: Node.on is accompanied by Node.off
  • [ ] TANDEM: tandem.addInstance is accompanied by tandem.removeInstance.
• [x] Do all types that require a dispose function have one? This should expose a public dispose function that calls this.disposeMyType(), where disposeMyType is a private function declared in the constructor. MyType should exactly match the filename.

PhET-iO

• [x] If the simulation is supposed to be instrumented for PhET-iO, please see How to Instrument a PhET Simulation for PhET-iO for the PhET-iO development process.

[pixelzoom]

5/11/17 dev meeting:

@jbphet will do memory testing and go through the checklist.

Plan A: Try to have this ready for @pixelzoom to do on Tuesday 5/16/17. Plan B: Have someone else do the review.

@jbphet assign to me when the sim is ready for review.

[pixelzoom]

Summary of 5/15/17 email update from @jbphet and @ariel-phet: Sim is not ready for review, so I won't be doing the code review. Someone else will be assigned to this issue when when the sim is ready.

[pixelzoom]

Hmm... I noticed that some of the items in the checklist are checked off. @jbphet are you checking them off as you do your own preliminary review?

[jbphet]

Yes I was. I can rescind those checkmarks if the intent was to have someone other than me go through the whole thing.

[pixelzoom]

This checklist was intended for the reviewer. But no harm in using it yourself, then unchecking everything before assigning it to the reviewer. Until then, everyone just needs to be aware that the checklist doesn't represent the status of the code review.

[jbphet]

I've unchecked them to avoid any confusion and will track my own progress on the list separately.

[jbphet]

Marking for dev meeting to draw straws and figure out who gets to do this review.

[jonathanolson]

I believe I've completed the code review to the depth that would be best. I haven't fully verified all of the logic (there is a lot required by this sim), but so far it looks good.

A few questions/notes that aren't covered by inline review comments or github issues:

• For naming, the 'EE' prefix seems somewhat inconsistently used (StartGameLevelNode, but has EECollectionAreaNode)? Unless there's a naming conflict with common code, I've found it nice to drop the prefix in past sims.
• There wasn't type documentation on a lot of object properties or methods. There were a number of places where having type documentation significantly helps readability, so I added some documentation as I went. Some @params and @returns or visibility documentation was also missing too. The ordering between visibility, @constructor, @returns, @params, and the main documentation seemed inconsistent, but seems to be fine to leave as-is. Documenting the parameters and return values of functions passed with {Function} would almost always be helpful. Keeping {Object} [options] as 'optional' be default is probably better for documentation, with a note if something named 'options' is required. Documenting the type of options in the _.extend is also helpful for readability, but I don't believe it's required by our style?
• Excellent documentation on how things work and what things do. Thanks!
• Text/RichText was never missing a PhetFont, which seems to be something I miss. Do you always add this when creating Text nodes, or is there another process I can use to make sure I don't forget this?
• Passing null as the initial shape to a Path is preferred to something that isn't used.
• Bounds have the same left, right, center, etc. as Nodes do, and is preferred to minX, maxX, etc. in layout code.
• Passing cornerRadius: radius in Rectangle options may be better than passing the radius two times in the parameters list.
• null or 'transparent' are the preferred "transparent" fill/stroke values (null preferred, except for cases where it is not allowed, like in a color Property).

I've left most review issues inline in the code (there were no major structural issues that would benefit from standalone issues). @jbphet, feel free to remove REVIEW statements at your discretion, or ideally create an issue referencing the line if there are questions or objections about the comment. Feedback on what review comments are helpful, and which are unhelpful or unneeded would be great!

Memory issues are most likely to be resolved by not recreating certain nodes in CoinNodeFactory, and reusing the results (through DAG usage). If that doesn't work (i.e. if it's a problem with Scenery's instance tree being too large), rasterization of coin parts may be helpful. Discussing with @jbphet on a call would be most helpful before memory work is done, so let me know when you're available.

[jonathanolson]

Checked off all issues that have pending review notes.

[jbphet]

Review and responses complete - closing.