[Tutor] importance of Docstring

A.T.Hofkamp a.t.hofkamp at tue.nl
Thu Apr 16 12:02:21 CEST 2009


mbikinyi brat wrote:
> Dear ALL,
> What is really the importance of Docstring in Python???
> Regards,
> Henry

The same as comments, except at function, class, and module level. In 
addition, Python provides hooks for extracting that information, and eg put it 
in a document such as the standardlib documentation.

Doc-strings are a means to document your design at the 'what' level rather 
than the lower 'how' level of code.


A short exercise:


def get_sum(val_lst):

   total = 0

   for val in val_lst:
     total = total + val

   return total


Now what does this function do?
This is a 'what' question, namely, from a design point of view, if I call this 
function, what does it do, and what is its result-value?



You have got the "how", namely you can read the code, and imagine what steps 
are taken to compute the return value.

You have to do several deduction steps from the code to answer the question.
1. "total" is returned, so that variable represents the return-value of the 
function.
2. total is initialized to 0
3. total is iteratively incremented with each value from the val_lst
4. the for-loop as a whole thus computes the sum of val_lst.
5. that value is returned as function return value.
6. val_lst is not modified
7. its data values are not modified either.

So the answer to the question "what does this function do?" is that it 
implements a sum function over a list (or even, an iterable).
Also, 'total' represents the sum of the values summed so far.

Experienced programmers see this in a fraction of a second for functions like 
above. However, if you have a 200-line function with 30 variables (which 
nobody here has of course, you all follow the PEP 8 guide lines :) ) and a 
complex flow of control between statements, the above deduction steps cost 
time and effort. Also, there is the chance that you make a mistake in your 
reasoning, or that the original author of the code made a mistake and your 
reasoning breaks down. Eg


total = 0

def get_sum(val_lst):

   for val in val_lst:
     total = total + val

   return total

Python has no problems whatsoever with this function. However, if you just 
read the function, it is not clear what the intention is. You'll have to find 
out how the global var 'total' is used to understand what the function does.


The above reasoning and/or deduction problems originate from the fact that you 
are trying to reason towards the higher "what" level of the function from the 
low "how" level.
Comments and doc-string are helpful to eliminate the reasoning effort:

def get_sum(val_lst):
   """
   Add all values from the 'val_lst' iterable together and return the sum.
   """

   total = 0   # Sum of values added so far.

   # Sum all values of the list.
   for val in val_lst:
     total = total + val

   return total

Now I have added some comment stating what the function does, what the meaning 
of the 'total' variable is, and what the purpose of the loop is.
Effectively, I have stated the 'what' reasoning results that we have deduced 
previously from the code.

Adding comments like this saves you the effort to do the same reasoning 
exercise I did before writing the code, and it eliminates some possible 
mistakes in your deduction reasoning.
In addition, it clearly states the intended function (the 'what') of the 
function as a whole, the variable and the parts of the code, making it easier 
for you to verify whether the code does the right thing at each point, thus 
making code-reviewing and bug-finding easier.

Now, tell me, what is easier?
1. Reading the whole code, doing the entire deduction process to discover what 
a function does, or
2. Read a single line in a doc-string or comment telling you exactly what you 
want to know.


Note that unlike popular belief, in my opinion, code should be written in such 
a way that it is easy to read. Code is written only once, and in general read 
about 3 times, I seem to remember (people have been researching this).
Code is much like any other document, the fact that a computer can also 
interpret it, should mostly be considered a lucky coindence.

Sincerely,
Albert


More information about the Tutor mailing list