Docstrings vs Comments

Question

I'm a bit confused over the difference between docstrings and comments in python.

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):

def term_work_mark(a0_mark, a1_mark, a2_mark, ex_mark, midterm_mark):      ''' (float, float, float, float, float) -> 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)      >>>term_work_mark(5, 5, 5, 5, 5)     11.8     >>>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) 

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.

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.

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?

Answer 1

It appears your teacher is a fan of How to Design Programs ;)

I'd tackle this as writing for two different audiences who won't always overlap.

First there are the docstrings; these are for people who are going to be using your code without needing or wanting to know how it works. Docstrings can be turned into actual documentation. Consider the official Python documentation - What's available in each library and how to use it, no implementation details (Unless they directly relate to use)

Secondly there are in-code comments; these are to explain what is going on to people (generally you!) who want to extend the code. These will not normally be turned into documentation as they are really about the code itself rather than usage. Now there are about as many opinions on what makes for good comments (or lack thereof) as there are programmers. My personal rules of thumb for adding comments are to explain:

• Parts of the code that are necessarily complex. (Optimisation comes to mind)
• Workarounds for code you don't have control over, that may otherwise appear illogical
• I'll admit to TODOs as well, though I try to keep that to a minimum
• Where I've made a choice of a simpler algorithm where a better performing (but more complex) option can go if performance in that section later becomes critical

Since you're coding in an academic setting, and it sounds like your lecturer is going for verbose, I'd say just roll with it. Use code comments to explain how you are doing what you say you are doing in the design recipe.

Answer 2

I believe that it's worth to mention what PEP8 says, I mean, the pure concept.

Docstrings

Conventions for writing good documentation strings (a.k.a. "docstrings") are immortalized in PEP 257.

Write docstrings for all public modules, functions, classes, and methods. Docstrings are not necessary for non-public methods, but you should have a comment that describes what the method does. This comment should appear after the def line.

PEP 257 describes good docstring conventions. Note that most importantly, the """ that ends a multiline docstring should be on a line by itself, e.g.:

"""Return a foobang  Optional plotz says to frobnicate the bizbaz first. """ 

For one liner docstrings, please keep the closing """ on the same line.

Comments

Block comments

Generally apply to some (or all) code that follows them, and are indented to the same level as that code. Each line of a block comment starts with a # and a single space (unless it is indented text inside the comment).

Paragraphs inside a block comment are separated by a line containing a single #.

Inline Comments

Use inline comments sparingly.

An inline comment is a comment on the same line as a statement. Inline comments should be separated by at least two spaces from the statement. They should start with a # and a single space.

Inline comments are unnecessary and in fact distracting if they state the obvious.

Don't do this:

x = x + 1 # Increment x

But sometimes, this is useful:

x = x + 1 # Compensate for border

Reference

• https://www.python.org/dev/peps/pep-0008/#documentation-strings
• https://www.python.org/dev/peps/pep-0008/#inline-comments
• https://www.python.org/dev/peps/pep-0008/#block-comments
• https://www.python.org/dev/peps/pep-0257/