Improve comments and naming, see phetsims/number-play#97

js/common/model/CountingPlayArea.ts

@@ -51,8 +51,6 @@ class CountingPlayArea extends CountingCommonModel {
 
   // contains any ten frames that are in the play area
   public readonly tenFrames: ObservableArray<TenFrame> | null;
-
-  // when the GroupLinkType is switched to no grouping, break apart any object groups
   public readonly groupingEnabledProperty: TReadOnlyProperty<boolean>;
 
   public constructor( highestCount: number, groupingEnabledProperty: TReadOnlyProperty<boolean>, name: string,
@@ -75,6 +73,7 @@ class CountingPlayArea extends CountingCommonModel {
 
     this.tenFrames = options.tenFrames;
 
+    // when grouping is turned off, break apart any object groups
     this.groupingEnabledProperty.lazyLink( groupingEnabled => {
       !groupingEnabled && this.breakApartCountingObjects( true );
     } );

js/common/model/NumberSuiteCommonPreferences.ts

@@ -29,12 +29,12 @@ class NumberSuiteCommonPreferences {
   public readonly showLabOnesProperty: Property<boolean>;
   public readonly readAloudProperty: Property<boolean>;
 
-  // True when the second locale can be turned on, because there are sufficient locales in the runtime.
-  public static readonly SECOND_LOCALE_SELECTION_AVAILABLE = availableRuntimeLocales.length > 1;
-
   // helper Properties derived from preference Properties
   public readonly secondLocaleStringsProperty: TReadOnlyProperty<SecondLocaleStrings>;
 
+  // True when the second locale can be turned on, because there are sufficient locales in the runtime.
+  public static readonly SECOND_LOCALE_SELECTION_AVAILABLE = availableRuntimeLocales.length > 1;
+
   public constructor() {
     this.readAloudProperty = new BooleanProperty( NumberSuiteCommonQueryParameters.readAloud );
 

js/common/view/CountingObjectCreatorPanel.ts

@@ -64,7 +64,7 @@ class CountingObjectCreatorPanel extends NumberSuiteCommonPanel {
     );
 
     const countingCreatorNode = new CountingCreatorNode( 0, countingPlayAreaNode, playArea.sumProperty,
-      playArea.resetEmitter, countingPlayAreaNode.addAndDragNumber.bind( countingPlayAreaNode ), {
+      playArea.resetEmitter, countingPlayAreaNode.addAndDragCountingObject.bind( countingPlayAreaNode ), {
       updateCurrentNumber: true,
       countingObjectTypeProperty: countingPlayAreaNode.countingObjectTypeProperty,
       groupingEnabledProperty: countingPlayAreaNode.playArea.groupingEnabledProperty,

js/common/view/CountingPlayAreaNode.ts

@@ -43,36 +43,44 @@ const COUNTING_OBJECT_REPEL_DISTANCE = 10; // empirically determined to look nic
 
 class CountingPlayAreaNode extends Node {
 
-  // Called with function( countingObjectNode ) on number splits
-  private readonly numberSplitListener: ( countingObjectNode: CountingObjectNode ) => void;
+  // called when a countingObjectNode is split, see onCountingObjectNodeSplit
+  private readonly splitListener: ( countingObjectNode: CountingObjectNode ) => void;
 
-  // Called with function( countingObjectNode ) when a number begins to be interacted with.
-  private readonly numberInteractionListener: ( countingObjectNode: CountingObjectNode ) => void;
+  // called when a countingObjectNode begins to be interacted with, see onNumberInteractionStarted
+  private readonly interactionListener: ( countingObjectNode: CountingObjectNode ) => void;
 
-  // Called with function( countingObject ) when a number finishes animation
-  private readonly numberAnimationFinishedListener: ( countingObject: CountingObject ) => void;
+  // called when a countingObject finishes animating, see onNumberAnimationFinished
+  private readonly animationFinishedListener: ( countingObject: CountingObject ) => void;
 
-  // Called with function( countingObject ) when a number finishes being dragged
-  private readonly numberDragFinishedListener: ( countingObjectNode: CountingObjectNode ) => void;
+  // called when a countingObjectNode finishes being dragged, see onNumberDragFinished
+  private readonly dragFinishedListener: ( countingObjectNode: CountingObjectNode ) => void;
+
+  // called when a countingObject's position was constrained, see preventOcclusion
   private readonly positionConstrainedListener: ( countingObject: CountingObject ) => void;
+
+  // see addAndDragCountingObject
+  private readonly addAndDragCountingObjectCallback: ( event: PressListenerEvent, countingObject: CountingObject ) => void;
+
+  // see tryToCombineCountingObjects
+  private readonly tryToCombineCountingObjectsCallback: ( draggedCountingObject: CountingObject ) => void;
+
+  // our model
   public readonly playArea: CountingPlayArea;
-  private readonly tryToCombineNumbersCallback: ( draggedCountingObject: CountingObject ) => void;
-  private readonly addAndDragNumberCallback: ( event: PressListenerEvent, countingObject: CountingObject ) => void;
 
   // CountingObject.id => {CountingObjectNode} - lookup map for efficiency
   private readonly countingObjectNodeMap: CountingObjectNodeMap;
 
-  // the bounds of the play area where counting objects can be dragged
+  // the bounds of the play area where countingObjects can be dragged
   public readonly playAreaBoundsProperty: TReadOnlyProperty<Bounds2>;
   public readonly countingObjectTypeProperty: TReadOnlyProperty<CountingObjectType>;
 
   // see options.viewHasIndependentModel for doc
   private readonly viewHasIndependentModel: boolean;
 
-  // Handle touches nearby to the numbers, and interpret those as the proper drag.
+  // handle touches nearby to the countingObjects, and interpret those as the proper drag.
   private readonly closestDragListener: ClosestDragListener;
 
-  // Parent for all CountingObjectNode instances, created if not provided.
+  // Node parent for all CountingObjectNode instances, created if not provided.
   private readonly countingObjectLayerNode: Node;
 
   public readonly countingObjectCreatorPanel: CountingObjectCreatorPanel;
@@ -98,22 +106,23 @@ class CountingPlayAreaNode extends Node {
 
     //TODO https://github.com/phetsims/number-suite-common/issues/29 TODO-TS Get rid of this binding pattern. Update function signatures in the attributes.
 
-    this.numberSplitListener = this.onNumberSplit.bind( this );
+    this.splitListener = this.onCountingObjectNodeSplit.bind( this );
 
-    this.numberInteractionListener = CountingPlayAreaNode.onNumberInteractionStarted.bind( this );
+    this.interactionListener = CountingPlayAreaNode.onNumberInteractionStarted.bind( this );
 
-    this.numberAnimationFinishedListener = this.onNumberAnimationFinished.bind( this );
+    this.animationFinishedListener = this.onNumberAnimationFinished.bind( this );
 
-    this.numberDragFinishedListener = ( countingObjectNode: CountingObjectNode ) => {
+    this.dragFinishedListener = ( countingObjectNode: CountingObjectNode ) => {
       this.onNumberDragFinished( countingObjectNode.countingObject );
     };
 
     this.positionConstrainedListener = ( countingObject: CountingObject ) => this.preventOcclusion( countingObject );
 
-    this.playArea = playArea;
+    this.addAndDragCountingObjectCallback = this.addAndDragCountingObject.bind( this );
+
+    this.tryToCombineCountingObjectsCallback = this.tryToCombineCountingObjects.bind( this );
 
-    this.tryToCombineNumbersCallback = this.tryToCombineNumbers.bind( this );
-    this.addAndDragNumberCallback = this.addAndDragNumber.bind( this );
+    this.playArea = playArea;
 
     this.countingObjectNodeMap = {};
 
@@ -192,12 +201,12 @@ class CountingPlayAreaNode extends Node {
   }
 
   /**
-   * Add a counting Object to the playArea and immediately start dragging it with the provided event.
+   * Add a countingObject to the playArea and immediately start dragging it with the provided event.
    *
    * @param event - The Scenery event that triggered this.
-   * @param countingObject - The counting Object to add and then drag
+   * @param countingObject - The countingObject to add and then drag
    */
-  public addAndDragNumber( event: PressListenerEvent, countingObject: CountingObject ): void {
+  public addAndDragCountingObject( event: PressListenerEvent, countingObject: CountingObject ): void {
 
     // Add it and lookup the related node.
     this.playArea.addCountingObject( countingObject );
@@ -215,8 +224,8 @@ class CountingPlayAreaNode extends Node {
     const countingObjectNode = new CountingObjectNode(
       countingObject,
       this.playAreaBoundsProperty,
-      this.addAndDragNumberCallback,
-      this.tryToCombineNumbersCallback, {
+      this.addAndDragCountingObjectCallback,
+      this.tryToCombineCountingObjectsCallback, {
         countingObjectTypeProperty: this.countingObjectTypeProperty,
         baseNumberNodeOptions: {
           handleOffsetY: COUNTING_OBJECT_HANDLE_OFFSET_Y
@@ -230,10 +239,10 @@ class CountingPlayAreaNode extends Node {
     this.closestDragListener.addDraggableItem( countingObjectNode );
 
     // add listeners
-    countingObjectNode.splitEmitter.addListener( this.numberSplitListener );
-    countingObjectNode.interactionStartedEmitter.addListener( this.numberInteractionListener );
-    countingObject.endAnimationEmitter.addListener( this.numberAnimationFinishedListener );
-    countingObjectNode.endDragEmitter.addListener( this.numberDragFinishedListener );
+    countingObjectNode.splitEmitter.addListener( this.splitListener );
+    countingObjectNode.interactionStartedEmitter.addListener( this.interactionListener );
+    countingObject.endAnimationEmitter.addListener( this.animationFinishedListener );
+    countingObjectNode.endDragEmitter.addListener( this.dragFinishedListener );
     countingObjectNode.positionConstrainedEmitter.addListener( this.positionConstrainedListener );
   }
 
@@ -244,10 +253,10 @@ class CountingPlayAreaNode extends Node {
     const countingObjectNode = this.getCountingObjectNode( countingObject );
 
     // Remove listeners
-    countingObjectNode.endDragEmitter.removeListener( this.numberDragFinishedListener );
-    countingObject.endAnimationEmitter.removeListener( this.numberAnimationFinishedListener );
-    countingObjectNode.interactionStartedEmitter.removeListener( this.numberInteractionListener );
-    countingObjectNode.splitEmitter.removeListener( this.numberSplitListener );
+    countingObjectNode.endDragEmitter.removeListener( this.dragFinishedListener );
+    countingObject.endAnimationEmitter.removeListener( this.animationFinishedListener );
+    countingObjectNode.interactionStartedEmitter.removeListener( this.interactionListener );
+    countingObjectNode.splitEmitter.removeListener( this.splitListener );
     countingObjectNode.positionConstrainedEmitter.removeListener( this.positionConstrainedListener );
 
     delete this.countingObjectNodeMap[ countingObjectNode.countingObject.id ];
@@ -267,7 +276,7 @@ class CountingPlayAreaNode extends Node {
   /**
    * When the user drops a counting Object they were dragging, see if it can combine with any other nearby counting Objects.
    */
-  public tryToCombineNumbers( draggedCountingObject: CountingObject ): void {
+  public tryToCombineCountingObjects( draggedCountingObject: CountingObject ): void {
     //TODO https://github.com/phetsims/number-suite-common/issues/29 This seems like a weird sidestep to try tenframes first and maybe be moved
     if ( this.tryToAddToTenFrame( draggedCountingObject ) ) {
       return;
@@ -416,9 +425,9 @@ class CountingPlayAreaNode extends Node {
   }
 
   /**
-   * Called when a counting Object node is split.
+   * Called when a countingObjectNode is split.
    */
-  private onNumberSplit( countingObjectNode: CountingObjectNode ): void {
+  private onCountingObjectNodeSplit( countingObjectNode: CountingObjectNode ): void {
     // this.playArea.splitCue.triggerFade();
   }
 

js/common/view/TenFrameNode.ts

@@ -39,7 +39,7 @@ class TenFrameNode extends Node {
 
   public readonly numberOfTenFrames: number;
 
-  // create and add a layer for the dots
+  // a Node layer for the dots
   private readonly dotsLayer: Node;
 
   // the center of every dot spot available

js/lab/view/SymbolCardCreatorPanel.ts

@@ -23,7 +23,6 @@ const SPACING = 10;
 
 class SymbolCardCreatorPanel extends NumberSuiteCommonPanel {
 
-  // create a map from SymbolType to countProperty
   private readonly symbolTypeToCountPropertyMap: Map<SymbolType, Property<number>>;
 
   // removes and disposes all types of symbol nodes