--- a/src/tile_map.cpp	Mon Oct 20 15:42:56 2008 +0000
+++ b/src/tile_map.cpp	Mon Oct 20 15:44:14 2008 +0000
@@ -14,13 +14,6 @@
  * @return Slope of the tile, except for the HALFTILE part */
 Slope GetTileSlope(TileIndex tile, uint *h)
 {
-	uint a;
-	uint b;
-	uint c;
-	uint d;
-	uint min;
-	uint r;
-
 	assert(tile < MapSize());
 
 	if (TileX(tile) == MapMaxX() || TileY(tile) == MapMaxY()) {
@@ -28,15 +21,27 @@
 		return SLOPE_FLAT;
 	}
 
-	min = a = TileHeight(tile);
-	b = TileHeight(tile + TileDiffXY(1, 0));
+	uint a = TileHeight(tile); // Height of the N corner
+	uint min = a; // Minimal height of all corners examined so far
+	uint b = TileHeight(tile + TileDiffXY(1, 0)); // Height of the W corner
 	if (min > b) min = b;
-	c = TileHeight(tile + TileDiffXY(0, 1));
+	uint c = TileHeight(tile + TileDiffXY(0, 1)); // Height of the E corner
 	if (min > c) min = c;
-	d = TileHeight(tile + TileDiffXY(1, 1));
+	uint d = TileHeight(tile + TileDiffXY(1, 1)); // Height of the S corner
 	if (min > d) min = d;
 
-	r = SLOPE_FLAT;
+	/* Due to the fact that tiles must connect with each other without leaving gaps, the
+	 * biggest difference in height between any corner and 'min' is between 0, 1, or 2.
+	 *
+	 * Also, there is at most 1 corner with height difference of 2.
+	 */
+
+	uint r = SLOPE_FLAT; // Computed slope of the tile
+
+	/* For each corner if not equal to minimum height:
+	 *  - set the SLOPE_STEEP flag if the difference is 2
+	 *  - add the corresponding SLOPE_X constant to the computed slope
+	 */
 	if ((a -= min) != 0) r += (--a << 4) + SLOPE_N;
 	if ((c -= min) != 0) r += (--c << 4) + SLOPE_E;
 	if ((d -= min) != 0) r += (--d << 4) + SLOPE_S;
@@ -55,10 +60,10 @@
 {
 	if (TileX(tile) == MapMaxX() || TileY(tile) == MapMaxY()) return 0;
 
-	uint h = TileHeight(tile);
-	h = min(h, TileHeight(tile + TileDiffXY(1, 0)));
-	h = min(h, TileHeight(tile + TileDiffXY(0, 1)));
-	h = min(h, TileHeight(tile + TileDiffXY(1, 1)));
+	uint h = TileHeight(tile); // N corner
+	h = min(h, TileHeight(tile + TileDiffXY(1, 0))); // W corner
+	h = min(h, TileHeight(tile + TileDiffXY(0, 1))); // E corner
+	h = min(h, TileHeight(tile + TileDiffXY(1, 1))); // S corner
 
 	return h * TILE_HEIGHT;
 }
@@ -71,10 +76,10 @@
 {
 	if (TileX(t) == MapMaxX() || TileY(t) == MapMaxY()) return 0;
 
-	uint h = TileHeight(t);
-	h = max(h, TileHeight(t + TileDiffXY(1, 0)));
-	h = max(h, TileHeight(t + TileDiffXY(0, 1)));
-	h = max(h, TileHeight(t + TileDiffXY(1, 1)));
+	uint h = TileHeight(t); // N corner
+	h = max(h, TileHeight(t + TileDiffXY(1, 0))); // W corner
+	h = max(h, TileHeight(t + TileDiffXY(0, 1))); // E corner
+	h = max(h, TileHeight(t + TileDiffXY(1, 1))); // S corner
 
 	return h * TILE_HEIGHT;
 }