title: Docstrings vs Comments
body: <p>I'm a bit confused over the difference between docstrings and comments in python. </p>
  
  <p>In my class my teacher introduced something known as a 'design recipe', a set of steps that will supposedly help us students plot and organize our coding better in Python. From what I understand, the below is an example of the steps we follow - this so call design recipe (the stuff in the quotations):</p>
  
  <pre><code>def term_work_mark(a0_mark, a1_mark, a2_mark, ex_mark, midterm_mark):
  
      ''' (float, float, float, float, float) -&gt; float
  
      Takes your marks on a0_mark, a1_mark, a2_mark, ex_mark and midterm_mark, 
      calculates their respective weight contributions and sums these 
      contributions to deliver your overall term mark out of a maximum of 55 (This
      is because the exam mark is not taken account of in this function)
  
      &gt;&gt;&gt;term_work_mark(5, 5, 5, 5, 5)
      11.8
      &gt;&gt;&gt;term_work_mark(0, 0, 0, 0, 0)
      0.0
      '''
  
      a0_component = contribution(a0_mark, a0_max_mark, a0_weight)
      a1_component = contribution(a1_mark, a1_max_mark, a1_weight)
      a2_component = contribution(a2_mark, a2_max_mark, a2_weight)
      ex_component = contribution(ex_mark, exercises_max_mark,exercises_weight)
      mid_component = contribution(midterm_mark, midterm_max_mark, midterm_weight)
      return (a0_component + a1_component + a2_component + ex_component + 
              mid_component)
  </code></pre>
  
  <p>As far as I understand this is basically a docstring, and in our version of a docstring it must include three things: a description, examples of what your function should do if you enter it in the python shell, and a 'type contract', a section that shows you what types you enter and what types the function will return.</p>
  
  <p>Now this is all good and done, but our assignments require us to also have comments which explain the nature of our functions, using the token '#' symbol.</p>
  
  <p>So, my question is, haven't I already explained what my function will do in the description section of the docstring? What's the point of adding comments if I'll essentially be telling the reader the exact same thing?</p>