search

phetsims / blackbody-spectrum

"Blackbody Spectrum" is an educational simulation in HTML5, by PhET Interactive Simulations.
GNU General Public License v3.0
1 stars 3 forks source link

code review #33

Closed pixelzoom closed 5 years ago

pixelzoom commented 6 years ago

@jbphet will assign this back to @pixelzoom when the sim is ready for code review.

I previously did an informal code review in https://github.com/phetsims/blackbody-spectrum/issues/15.

jbphet commented 6 years ago

I'm going to unassign this for a bit - we just did a "pixel polishing" review and came up with a number of things to change (see https://github.com/phetsims/blackbody-spectrum/issues/34), so I'll assign this once those items are taken care of.

jbphet commented 6 years ago

In the 9/27/2018 developer meeting it was decided that @chrisklus would do the code review instead of @pixelzoom when this is ready.

chrisklus commented 5 years ago

PhET code-review checklist

Build and Run Checks

Memory Leaks

Performance, Usability

Internationalization

Guidelines for string keys are:

(1) Strings keys should generally match their values. E.g.:

"helloWorld": {
  value: "Hello World!"
},
"quadraticTerms": {
  value: "Quadratic Terms"
}

(2) If a string key would be exceptionally long, use a key name that is an abbreviated form of the string value, or that captures the purpose/essence of the value. E.g.:

// key is abbreviated
"iWentToTheStore": {
  value: "I went to the store to get milk, eggs, butter, and sugar."
},

// key is based on purpose
"describeTheScreen": {
  value: "The Play Area is a small room. The Control Panel has buttons, a checkbox, and radio buttons to change conditions in the room."
}

(3) If string key names would collide, use your judgment to disambiguate. E.g.:

"simplifyTitle": {
   value: "Simplify!"
},
"simplifyCheckbox": {
   value: "simplify"
}

(4) String keys for screen names should have the general form "screen.{{screenName}}". E.g.:

  "screen.explore": {
    "value": "Explore"
  },

(5) String patterns that contain placeholders (e.g. "My name is {{first}} {{last}}") should use keys that are unlikely 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

   my-repo/
      assets/
      audio/
         license.json
      doc/
         images/
               *see annotation
         model.md
         implementation-notes.md
      images/
         license.json
      js/
         (see section below)
      dependencies.json
      .gitignore
      my-repo_en.html
      my-repo-strings_en.json
      Gruntfile.js
      LICENSE
      package.json
      README.md

*Any images used in model.md or implementation-notes.md should be added here. Images specific to aiding with documentation do not need their own license.

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

Coding Conventions

var numPart;            // incorrect
var numberOfParticles;  // correct

var width;              // incorrect
var beakerWidth;        // correct
// modules
var inherit = require( 'PHET_CORE/inherit' );
var Line = require( 'SCENERY/nodes/Line' );
var Rectangle = require( 'SCENERY/nodes/Rectangle' );

// strings
var kineticString = require( 'string!ENERGY/energy.kinetic' );
var potentialString = require( 'string!ENERGY/energy.potential' );
var thermalString = require( 'string!ENERGY/energy.thermal' );

// images
var energyImage = require( 'image!ENERGY/energy.png' );

// audio
var kineticAudio = require( 'audio!ENERGY/energy' );

For example, this constructor uses parameters for everything. At the call site, the semantics of the arguments are difficult to determine without consulting the constructor.

/**
 * @param {Ball} ball - model element
 * @param {Property.<boolean>} visibleProperty - is the ball visible?
 * @param {Color|string} fill - fill color
 * @param {Color|string} stroke - stroke color
 * @param {number} lineWidth - width of the stroke
 * @constructor
 */
function BallNode( ball, visibleProperty, fill, stroke, lineWidth ){
   // ...
}

// Call site
var ballNode = new BallNode( ball, visibleProperty, 'blue', 'black', 2 );

Here’s the same constructor with an appropriate use of options. The call site is easier to read, and the order of options is flexible.

/**
 * @param {Ball} ball - model element
 * @param {Property.<boolean>} visibleProperty - is the ball visible?
 * @param {Object} [options]
 * @constructor
 */
function BallNode( ball, visibleProperty, options ) {

  options = _.extend( {
    fill: 'white',  // {Color|string} fill color
    stroke: 'black', // {Color|string} stroke color
    lineWidth: 1 // {number} width of the stroke
  }, options );

  // ...
}

// Call site
var ballNode = new BallNode( ball, visibleProperty, {
  fill: 'blue',
  stroke: 'black',
  lineWidth: 2
} );

Example:

/**
 * @param {ParticleBox} particleBox - model element
 * @param {Property.<boolean>} visibleProperty - are the box and its contents visible?
 * @param {Object} [options]
 * @constructor
 */
function ParticleBoxNode( particleBox, visibleProperty, options ) {

  options = _.extend( {
    fill: 'white',  // {Color|string} fill color
    stroke: 'black', // {Color|string} stroke color
    lineWidth: 1, // {number} width of the stroke
    particleNodeOptions: null, // {*} to be filled in with defaults below
  }, options );

  options.particleNodeOptions = _.extend( {
    fill: 'red',
    stroke: 'gray',
    lineWidth: 0.5
  }, options.particleNodeOptions );

  // add particle
  this.addChild( new ParticleNode( particleBox.particle, options.particleNodeOptions ) );

  .
  .
  .

}

A possible exception to this guideline is when the constructor API is improved by hiding the implementation details, i.e. not revealing that a sub-component exists. In that case, it may make sense to use new top-level options. This is left to developer and reviewer discretion.

For more information on the history and thought process around the "nested options" pattern, please see https://github.com/phetsims/tasks/issues/730.

/**
 * The PhetDeveloper is responsible for creating code for simulations
 * and documenting their code thoroughly.
 *
 * @param {string} name - full name
 * @param {number} age - age, in years
 * @param {boolean} isEmployee - whether this developer is an employee of CU
 * @param {function} callback - called immediate after coffee is consumed
 * @param {Property.<number>} hoursProperty - cumulative hours worked
 * @param {string[]} friendNames - names of friends
 * @param {Object} [options] - optional configuration, see constructor
 * @constructor
 */
function PhetDeveloper( name, age, isEmployee, callback, hoursProperty, friendNames, options ) {}
var self = this;
someProperty.link( function(){
  self.doSomething();
} );
this.doSomethingElse();
  return inherit( Object, Line, {

   /**
    * Gets the slope of the line
    * @returns {number}
    */
    getSlope: function() {
      if ( this.undefinedSlope() ) {
        return Number.NaN;
      }
      else {
        return this.rise / this.run;
      }
    },

    /**
     * Given x, solve y = m(x - x1) + y1.  Returns NaN if the solution is not unique, or there is no solution (x can't
     * possibly be on the line.)  This occurs when we have a vertical line, with no run.
     * @param {number} x - the x coordinate
     * @returns {number} the solution
     */
    solveY: function( x ) {
      if ( this.undefinedSlope() ) {
        return Number.NaN;
      }
      else {
        return ( this.getSlope() * ( x - this.x1 ) ) + this.y1;
      }
    }
  } );

// OK isFaceSmile ? self.smile() : self.frown();

// OK if ( isFaceSmile ) { self.smile(); } else { self.frown(); }


- [x] It is not uncommon to use conditional shorthand and short circuiting for invocation.

```js
( expression ) && statement;
( expression ) ? statement1 : statement2;
( foo && bar ) ? fooBar() : fooCat();
( foo && bar ) && fooBar();
( foo && !(bar && fooBar)) && nowIAmConfused();
this.fill = ( foo && bar ) ? 'red' : 'blue';

If the expression is only one item, the parentheses can be omitted. This is the most common use case.

assert && assert( happy, ‘Why aren\’t you happy?’ );
happy && smile();
var thoughts = happy ? ‘I am happy’ : ‘I am not happy :(’;
// Randomly choose an existing crystal to possibly bond to
var crystal = this.crystals.get( _.random( this.crystals.length - 1 ) );

// Find a good configuration to have the particles move toward
var targetConfiguration = this.getTargetConfiguration( crystal );
Visibility Annotations

Because JavaScript lacks visibility modifiers (public, protected, private), PhET uses JSdoc visibility annotations to document the intent of the programmer, and define the public API. Visibility annotations are required for anything that JavaScript makes public. Information about these annotations can be found here. (Note that other documentation systems like the Google Closure Compiler use slightly different syntax in some cases. Where there are differences, JSDoc is authoritative. For example, use Array.<Object> or Object[] instead of Array<Object>). PhET guidelines for visibility annotations are as follows:

/**
 * Creates the icon for the "Energy" screen, a cartoonish bar graph.
 * @returns {Node}
 * @public
 */
// @public Adds a {function} listener
addListener: function( listener ) { /*...*/ }

Math Libraries

IE11

Organization, Readability, Maintainability

arnabp commented 5 years ago

Sim is now ready for code review

chrisklus commented 5 years ago

Review complete. Looking good @arnabp, nice work!

Any items on the checklist that are not checked have been marked with a corresponding "UPDATE:", with a link to the work that needs to be done to finish that item. There are other incomplete items on the checklist that have been checked off because the remaining work for them is outlined with REVIEW comments in code. There are 53 REVIEWs marked in the code, most of which are minor.

arnabp commented 5 years ago

I've fixed up all REVIEW comments and resolved the code review referenced issues. Ready for @chrisklus to check that all relevant changes have been made.

chrisklus commented 5 years ago

Looks really good @arnabp, nice work. I reviewed the relevant issues and checked off their corresponding boxes.

https://github.com/phetsims/blackbody-spectrum/issues/74 is the only issue that requires any more work, so I'm going to close this issue.