From 3665481649bc9e2ac34f31504a70d93aa5bd44c9 Mon Sep 17 00:00:00 2001
From: Peter Wu <lekensteyn@gmail.com>
Date: Mon, 2 Dec 2013 23:17:46 +0100
Subject: Improve comments

Merge two subsequent translations in draw(), add a lecture. Replace
gl.glColor3f by a call that explicitly names the use of black in
drawScene().
---
 src/Robot.java     | 37 +++++++++++++++++++++++++++++++------
 src/RobotRace.java |  5 +++--
 2 files changed, 34 insertions(+), 8 deletions(-)

diff --git a/src/Robot.java b/src/Robot.java
index 7d69460..3fe4377 100644
--- a/src/Robot.java
+++ b/src/Robot.java
@@ -61,22 +61,26 @@ class Robot extends BetterBase {
      * Draws this robot (as a {@code stickfigure} if specified).
      */
     public void draw(boolean stickFigure) {
+        // before drawing body parts, configure whether to draw a full body or
+        // just a stick figure with joints and such.
         this.asStickFigure = stickFigure;
-        // as the components are drawn with the torso as center, move it up
-        gl.glPushMatrix();
-        gl.glTranslatef(0, 0, torsoHeight / 2 + legLength);
 
         // These materials control the reflected light
         gl.glMaterialfv(GL_FRONT, GL_AMBIENT_AND_DIFFUSE, material.diffuse, 0);
         gl.glMaterialfv(GL_FRONT, GL_SPECULAR, material.specular, 0);
 
-        gl.glTranslatef(0, 0, footHeight);
+        // save positions so it can be restored easily later
+        gl.glPushMatrix();
+        // position the center of the torso above the Z axis such that the foot
+        // stands on the XY plane.
+        gl.glTranslatef(0, 0, torsoHeight / 2 + legLength + footHeight);
 
         // Draw the robot, everything is relative to the center of torso.
-        // Static parts:
+
+        // Static parts (that do not animate):
         drawTorso();
         drawHead();
-        // only draw the circles in normal, full body mode
+        // only draw the shoulder parts in normal, full body mode
         if (!asStickFigure) {
             drawShoulderTop();
         }
@@ -89,6 +93,20 @@ class Robot extends BetterBase {
         drawArm(false);
         drawArm(true);
 
+        //<editor-fold>
+        // The following function call exist to make a point clear. Adding
+        // comments for the sake of having comments is silly, pointless and an
+        // outdated idea. Self-documenting code (by using appropriate symbol
+        // names and logical structures) is much more useful than adding
+        // comments for every statement (50% comments...). High-level
+        // descriptions of functionality could be given in a design document or
+        // added as comments, but something like "draws a leg" for a function
+        // named "drawLeg" is useless. If you want to know what exactly happens,
+        // look in the method code, it likely contains some comments to
+        // describe what happens.
+        thisFunctionDoesAbsolutelyNothing();
+        //</editor-fold>
+
         // restore position
         gl.glPopMatrix();
     }
@@ -131,6 +149,7 @@ class Robot extends BetterBase {
                 setColor(color);
             }
         }
+        // turn a cube into a small beam
         gl.glScalef(x, y, z);
         glut.glutSolidCube(1);
         // return to previous scales
@@ -287,4 +306,10 @@ class Robot extends BetterBase {
         gl.glPopMatrix();
     }
 
+    /**
+     * This function does nothing, its use is described at the caller in
+     * Rboot.draw().
+     */
+    private void thisFunctionDoesAbsolutelyNothing() {
+    }
 }
diff --git a/src/RobotRace.java b/src/RobotRace.java
index 5b8f6a7..a7fc2e7 100644
--- a/src/RobotRace.java
+++ b/src/RobotRace.java
@@ -223,7 +223,8 @@ public class RobotRace extends Base {
         // Enable lighting effects
         if (lightingEnabled) {
             float[] lightPos = {
-                // light position (slightly away from top-left corner)
+                // light position (slightly away from top-left corner of the
+                // camera (eye) point)
                 (float) camera.eye.x(),
                 (float) camera.eye.y() + 1f,
                 (float) camera.eye.z() - 1f,
@@ -256,7 +257,7 @@ public class RobotRace extends Base {
         gl.glClear(GL_DEPTH_BUFFER_BIT);
 
         // Set color to black.
-        gl.glColor3f(0f, 0f, 0f);
+        BetterBase.setColor(Color.BLACK);
 
         gl.glPolygonMode(GL_FRONT_AND_BACK, GL_FILL);
 
-- 
cgit v1.2.1