Clarifying a bit on commented code

diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst
index b27f8da..c4cb0fd 100644 (file)
--- a/docs/writing/documentation.rst
+++ b/docs/writing/documentation.rst
@@ -104,26 +104,38 @@ line. Good editors allow to do this with few keystrokes (ctrl-v on Vim).
 
     def tricky_function():
         '''
+        Commented out because its breaks something.
         if foo:
             do_bar()
         '''
         return baz
 
     def tricky_function():
+        # Commented out because its breaks something.
         #if foo:
             #do_bar()
         return baz
 
+
+    def tricky_function():
+    # Commented out because its breaks something.
+    #   if foo:
+    #       do_bar()
+        return baz
+
 **Good**
 
 .. code-block:: python
 
     def tricky_function():
+        # Commented out because its breaks something.
         #if foo:
         #    do_bar()
         return baz
 
-
+Note that comment text is properly written and separated from the hash by a
+space. Commented code is not separated from the hash by an additional space;
+this helps when uncommented the code.
 
 The Basics
 ::::::::::