Merge pull request #656 from swcarpentry/martinosorb-patch-2

add more detailed description of comments vs docstrings

episodes/18-style.md

@@ -128,6 +128,14 @@ def overall_max(sequences):
 
 ## Document This
 
+Use comments to describe and help others understand potentially unintuitive
+sections or individual lines of code. They are especially useful to whoever
+may need to understand and edit your code in the future, including yourself.
+
+Use docstrings to document the acceptable inputs and expected outputs of a method
+or class, its purpose, assumptions and intended behavior. Docstrings are displayed
+when a user invokes the builtin `help` method on your method or class.
+
 Turn the comment in the following function into a docstring
 and check that `help` displays it properly.