(all) doc & better code quality

closes #1

Author: AkselsLedins

config/config.go

@@ -20,8 +20,13 @@ type uiConfig struct {
 	VehicleDefaultColor color.RGBA
 }
 
+type simulationConfig struct {
+	Bonus int
+}
+
 type config struct {
-	UI uiConfig
+	UI         uiConfig
+	Simulation simulationConfig
 }
 
 var Config config
@@ -34,4 +39,6 @@ func init() {
 	Config.UI.VehicleDefaultColor = colornames.Red
 	Config.UI.GridColor = colornames.Gray
 	Config.UI.WindowTitle = "Google Hashcode 2018 - Simulator!"
+
+	Config.Simulation.Bonus = 2
 }

ghashcode/coordinates.go

@@ -1,5 +1,7 @@
 package ghashcode
 
+// Coordinates export a type that look like
+// coordinates on a map
 type Coordinates struct {
 	X, Y int32
 }

ghashcode/trip.go

@@ -10,62 +10,72 @@ import (
 
 	"github.com/faiface/pixel"
 	"github.com/faiface/pixel/imdraw"
-	"github.com/faiface/pixel/pixelgl"
 )
 
+// Trip a structure which represents a trip in the simulation
+// Quite self-explanatory
 type Trip struct {
+	// unique identifier for each trip, used for debugging
 	ID int
 
+	// start & end coordinates
 	Start Coordinates
 	End   Coordinates
 
+	// computed distance from Start to End
+	// helps for score computation
 	Distance int
-	Bonus    int
+	// we set there the bonus defined in Config if the
+	// driver starts its trip on time
+	Bonus int
 
+	// A driver cannot start its trip before EarlierStart step
+	// And if he finish his drive after LatestFinish the trip will
+	// be marked as failed
 	EarliestStart int32
 	LatestFinish  int32
 
+	// current color of the trip
 	Color color.RGBA
 
-	Taken      bool
+	// when a driver is going towards the trip
+	Taken bool
+	// the vehicle is actually doing it
 	InProgress bool
-	Failed     bool
-
-	// precomputed values
-	GraphicLine *imdraw.IMDraw
-}
-
-func (t *Trip) DrawToWindow(win *pixelgl.Window) {
-	if !t.Taken {
-		return
-	}
-
-	t.GraphicLine.Color = t.Color
-	t.GraphicLine.Draw(win)
+	// the vehicle end the trip too late
+	Failed bool
 }
 
+// AddToImd adds to the imd batch the graphic line of the trip
+// We only call .draw once for all the trips
 func (t *Trip) AddToImd(imd *imdraw.IMDraw) {
+	// we only show taken trips for performance
+	// TODO a way to desactivate this
 	if !t.Taken {
 		return
 	}
 
+	// depending of the status of the trip we assign it a color
 	imd.Color = t.Color
 
-	/* start point */
+	// start point
 	startX := t.Start.X*config.Config.UI.SquareSize + config.Config.UI.SquareSize
 	startY := t.Start.Y*config.Config.UI.SquareSize + config.Config.UI.SquareSize
 	imd.Push(pixel.V(float64(startX), float64(startY)))
-	/* second point */
+	// second point
 	intermediateX := (t.End.X)*config.Config.UI.SquareSize + config.Config.UI.SquareSize
 	intermediateY := (t.Start.Y)*config.Config.UI.SquareSize + config.Config.UI.SquareSize
 	imd.Push(pixel.V(float64(intermediateX), float64(intermediateY)))
-	/* final point */
+	// third final point
 	endX := t.End.X*config.Config.UI.SquareSize + config.Config.UI.SquareSize
 	endY := t.End.Y*config.Config.UI.SquareSize + config.Config.UI.SquareSize
 	imd.Push(pixel.V(float64(endX), float64(endY)))
 
+	// registering the line
 	imd.Line(2)
 
+	// we create the tip of the trip to see where its start is
+	// looks like this:       O---------
 	imd.Color = t.Color
 	imd.EndShape = imdraw.RoundEndShape
 
@@ -75,28 +85,40 @@ func (t *Trip) AddToImd(imd *imdraw.IMDraw) {
 	imd.Line(10)
 }
 
+// SetStart setter for StartCoordinates
 func (t *Trip) SetStart(x, y int32) {
 	t.Start.X = x
 	t.Start.Y = y
 }
 
+// SetEnd setter for StartCoordinates
 func (t *Trip) SetEnd(x, y int32) {
 	t.End.X = x
 	t.End.Y = y
 }
 
+// SomeoneIsOnIt we could store the vehicle id for debugging purposes there
+// but atm we only change the trip color and its status
 func (t *Trip) SomeoneIsOnIt() {
 	t.Color = colornames.Beige
 	t.Taken = true
 }
 
+// StartTrip takes the current step as parameter
+// if we start it on time we earn the bonus points
+// a different color is assigned if we start it on time or not
 func (t *Trip) StartTrip(step int) {
 	if step == int(t.EarliestStart) {
-		t.Bonus += 2
+		t.Bonus += config.Config.Simulation.Bonus
+		t.Color = colornames.Gold
+		return
 	}
 	t.Color = colornames.Cyan
 }
 
+// Finish the vehicle finished the trip at step.
+// we determine if he failed or not to arrive on time
+// a different is assigned if we end it on time or not
 func (t *Trip) Finish(step int32) int {
 	failed := false
 	if step > t.LatestFinish {
@@ -107,16 +129,19 @@ func (t *Trip) Finish(step int32) int {
 	if !failed {
 		t.Color = colornames.Green
 		return t.Distance + t.Bonus
-	} else {
-		t.Color = colornames.Red
-		return 0
 	}
+	t.Color = colornames.Red
+	return 0
 }
 
+// WarnEarly it changes only the trip color to warn graphically
+// that a vehicle is too early on a trip
+// We can see that way that some drivers are waiting way too long
 func (t *Trip) WarnEarly() {
 	t.Color = colornames.Yellow
 }
 
+// NewTrip a constructor for Trip
 func NewTrip(id int, a, b, x, y, s, f int32) *Trip {
 	trip := new(Trip)
 
@@ -141,7 +166,5 @@ func NewTrip(id int, a, b, x, y, s, f int32) *Trip {
 	imd.Color = trip.Color
 	imd.EndShape = imdraw.RoundEndShape
 
-	trip.GraphicLine = imd
-
 	return trip
 }

ghashcode/vehicle.go

@@ -8,15 +8,24 @@ import (
 	"github.com/faiface/pixel/imdraw"
 )
 
+// Vehicle a structure which represents a vehicle in the simulation
+// Quite self-explanatory
 type Vehicle struct {
+	// current position of the vehicle
 	CurrentPosition Coordinates
 
-	CurrentRide int
-	OnRide      bool
-	Trips       []int32
-	Enabled     bool
+	// Trips an array of trips' indexes
+	// (and not their ids)
+	Trips []int32
+	// index of the current trip in Trips
+	CurrentTrip int
+	// if he is currently assigned on a trip
+	OnRide  bool
+	Enabled bool
 }
 
+// AddToImd adds to the imd batch the graphic point of the vehicle
+// We only call .draw once for all the vehicles
 func (v *Vehicle) AddToImd(imd *imdraw.IMDraw) {
 	imd.Color = config.Config.UI.VehicleDefaultColor
 	imd.EndShape = imdraw.RoundEndShape
@@ -34,18 +43,13 @@ func (v *Vehicle) AddToImd(imd *imdraw.IMDraw) {
 	imd.Line(config.Config.UI.VehicleSize)
 }
 
-func (v *Vehicle) SetPosition(x, y int32) {
-	v.CurrentPosition.X = x
-	v.CurrentPosition.Y = y
-}
-
 func (v *Vehicle) Drive(allTrips []*Trip, step int) (score int) {
 	// it has done every of his trips
-	if v.CurrentRide >= len(v.Trips) {
+	if v.CurrentTrip >= len(v.Trips) {
 		return
 	}
 
-	tripToGoTo := allTrips[v.Trips[v.CurrentRide]]
+	tripToGoTo := allTrips[v.Trips[v.CurrentTrip]]
 
 	if v.OnRide {
 		tripToGoTo.StartTrip(step)
@@ -54,8 +58,8 @@ func (v *Vehicle) Drive(allTrips []*Trip, step int) (score int) {
 			return
 		}
 		v.DriveOnTrip(tripToGoTo.End.X, tripToGoTo.End.Y)
-		cx, cy := v.GetPosition()
-		if cx == tripToGoTo.End.X && cy == tripToGoTo.End.Y {
+		currentX, currentY := v.GetPosition()
+		if currentX == tripToGoTo.End.X && currentY == tripToGoTo.End.Y {
 			score += tripToGoTo.Finish(int32(step))
 			v.NextTrip()
 			return
@@ -68,71 +72,103 @@ func (v *Vehicle) Drive(allTrips []*Trip, step int) (score int) {
 	return
 }
 
-func (v *Vehicle) GetPosition() (int32, int32) {
-	return v.CurrentPosition.X, v.CurrentPosition.Y
-}
-
+// NextTrip move forward next trip or disable the vehicle
+// if there isnt any trips left
 func (v *Vehicle) NextTrip() {
-	// move forward next trip
-	v.CurrentRide++
+	v.CurrentTrip++
 	v.OnRide = false
-	if v.CurrentRide >= len(v.Trips) {
-		// no trip ? hide the car
+
+	// no trip ? hide the car
+	if v.CurrentTrip >= len(v.Trips) {
 		v.Enabled = false
 	}
 }
 
-func (v *Vehicle) DriveOnTrip(x, y int32) {
-	cx, cy := v.GetPosition()
-	if cx > x {
-		cx--
-	} else if cx < x {
-		cx++
-	} else if cy > y {
-		cy--
-	} else if cy < y {
-		cy++
+// DriveOnTrip it will make the vehicle
+// follow the line drawn on the screen by the trip
+func (v *Vehicle) DriveOnTrip(destinationX, destinationY int32) {
+	currentX, currentY := v.GetPosition()
+	if currentX > destinationX {
+		currentX--
+	} else if currentX < destinationX {
+		currentX++
+	} else if currentY > destinationY {
+		currentY--
+	} else if currentY < destinationY {
+		currentY++
 	}
-	v.SetPosition(cx, cy)
+
+	// update vehicle position
+	v.SetPosition(currentX, currentY)
 }
 
-func (v *Vehicle) DriveTo(x, y int32) {
-	cx, cy := v.GetPosition()
-	dx := math.Abs(float64(cx - x))
-	dy := math.Abs(float64(cy - y))
+// DriveTo destinationX, destinationY coordinates
+// It will make the vehicle move in a straight line to a point
+func (v *Vehicle) DriveTo(destinationX, destinationY int32) {
+	// retrieve current position
+	currentX, currentY := v.GetPosition()
 
-	// fmt.Printf("goto %d %d\n", x, y)
-	nx := cx
-	ny := cy
+	// calculate the absolute difference between the positions
+	dx := math.Abs(float64(currentX - destinationX))
+	dy := math.Abs(float64(currentY - destinationY))
+
+	// newX and newY
+	nx := currentX
+	ny := currentY
 	if dx < dy {
-		if cy < y {
+		if currentY < destinationY {
 			ny++
-		} else if cy > y {
+		} else if currentY > destinationY {
 			ny--
 		}
 	} else if dx > dy {
-		if cx < x {
+		if currentX < destinationX {
 			nx++
-		} else if cx > x {
+		} else if currentX > destinationX {
 			nx--
 		}
 	} else if dx == dy {
-		if cx < x {
+		if currentX < destinationX {
 			nx++
-		} else if cx > x {
+		} else if currentX > destinationX {
 			nx--
-		} else if cy < y {
+		} else if currentY < destinationY {
 			ny++
-		} else if cy > y {
+		} else if currentY > destinationX {
 			ny--
 		}
 	}
-	// fmt.Printf("driving to %d, %d\n", x, y)
-	// fmt.Printf("current pos [%d, %d]", v.CurrentPosition.X, v.CurrentPosition.Y)
-	// fmt.Printf("-\n")
-	// fmt.Printf("moving from (%d, %d) to (%d, %d)\n", cx, cy, nx, ny)
+
+	// update the vehicle position
 	v.SetPosition(nx, ny)
-	if x == nx && y == ny {
+
+	// it reached his destination so we can consider him ready to start his ride
+	if destinationX == nx && destinationY == ny {
 		v.OnRide = true
 	}
 }
+
+// NewVehicle a constructor for Trip
+// takes its trips as parameters
+func NewVehicle(trips []int32) *Vehicle {
+	v := new(Vehicle)
+
+	// default values
+	v.SetPosition(0, 0)
+	v.Enabled = true
+	v.CurrentTrip = 0
+	v.Trips = trips
+
+	return v
+}
+
+// SetPosition setter for CurrentPosition
+func (v *Vehicle) SetPosition(x, y int32) {
+	v.CurrentPosition.X = x
+	v.CurrentPosition.Y = y
+}
+
+// GetPosition getter for CurrentPosition
+func (v *Vehicle) GetPosition() (int32, int32) {
+	return v.CurrentPosition.X, v.CurrentPosition.Y
+}