How useful documentation is? (docstring)

Question

I still dont get it, the programmer can inspect the comment during run time..

Answer 1

a "docstring" describes what your function or algorithm does and how it achieves it. For example if you had a function that staples paper, your docstring at the start of that function would describe that it staples paper together using staples. it takes one argument (paper) and returns the stapled paper.
A comment is anything and placed anywhere to make small mentions within the algorithm, where as the docstring describes the entire function.

Does it stop you from using one or the other? no, but some software can read docstrings attached to a function, where as comments are generally ignored.

Answer 2

no, not unless you tell the function to specifically do that. A docstring has the same behavior as comment #'s, but it's good coding practice to put a docstring at the start of your function or algorithm to describe what it does. it saves the programmer a lot of time.

Look at it from another point of view. As the one creating the program/function, it seems rather counter productive to write docstrings or comments. As you and other programmers can get the idea by reading it.

However ... as the program gets bigger or more complex, you need documentation to explain what parts of your program do what and when. This is where docstrings come in as well. They sit at the very start of the function/program and explain what the entire thing does. Otherwise to understand what it does, they'd need to skim your entire algorithm.

Answer 3

So, docstring will print the description of staples on screen?

Answer 4

Oh, thank you for the explanation. But I still dont get it.

Maybe I have to practice python in a real sim (pc) rather just in a phone..

Answer 5

Example use of docstrings and comments together:

def calcDistance (x,y,x2,y2):
" " "
Calculates the distance between two
points, then returns the result.
x = 1st point x coordinate
y = 1st point y coordinate
x2 = 2nd point x coordinate
y2 = 2nd point y coordinate
" " "
# sqrt is a built-in python function for
# square root.
result = sqrt ( (x - x2)**2 + (y - y2)**2 )
return result