Remove unnecessary comments, add a descriptive comment and a short paragraph explaining what comments are for (fixes OpenTechSchool#34)

projectgus · projectgus · commit 371e9720c776 · 2013-06-22T18:18:03.000+10:00
diff --git a/docs/en/functions.rst b/docs/en/functions.rst
@@ -75,11 +75,26 @@ Solution
       turtle.forward(50)
       turtle.left(90)
 
-    angle = 20            # <--
+    # Set the angle we want to use for our square
+    angle = 20
     tilted_square()
     tilted_square()
     tilted_square()
 
+Comments
+--------
+
+In the solution above, the line that starts with a ``#`` is called a
+comment. In Python, anything that goes on a line after ``#`` is ignored
+by the computer. Use comments to explain what your program does,
+without changing the behaviour for the computer.
+
+Comments can also go at the end of a line, like this:
+
+::
+
+     angle = 20 # Set the angle we want to use for our square
+
 
 A function for a hexagon
 ========================
diff --git a/docs/en/simple_drawing.rst b/docs/en/simple_drawing.rst
@@ -176,7 +176,7 @@ Solution
 
 ::
 
-    turtle.left(20)     # <--
+    turtle.left(20)
 
     turtle.forward(50)
     turtle.left(90)
@@ -187,7 +187,7 @@ Solution
     turtle.forward(50)
     turtle.left(90)
 
-    turtle.left(20)     # <--
+    turtle.left(20)
 
     turtle.forward(50)
     turtle.left(90)
@@ -198,7 +198,7 @@ Solution
     turtle.forward(50)
     turtle.left(90)
 
-    turtle.left(20)     # <--
+    turtle.left(20)
 
     turtle.forward(50)
     turtle.left(90)
diff --git a/docs/en/variables.rst b/docs/en/variables.rst
@@ -67,7 +67,9 @@ Solution
     turtle.left(90)
 
     turtle.left(angle)
-    # ...
+
+
+... and so on
 
 Bonus
 -----
