are docstrings for variables a bad idea?

[Diez B. Roggisch]

jelle wrote:

> That's basically the idea...
> Often i find myself annotating what variables actually stand for, so to
> refer back to the code in half a year or so.
> 
>  # check if ID's or coords
> self.pointIDs = ptIDs
> self.coords   = [tuple(RS.PointCoordinates(i)) for i in ptIDs]

You aren't annotating variables - you describe what the next lines are
supposed to do, possibly involving new variables. Nothing new here...

I don't know for sure what you mean by "pop up as doc-string" - I guess you
want them magically merged into the functions doc string, at least inside
your editor? That sure could be done - but I personally don't think that is
too useful. Because you lose context. It might be that a particular comment
only applies inside an if-statement. So at least indention should be
preserved. But then - why not just look at the source...

IMHO commenting the parameters and results of a function is what someone
needs who skims the docs for enlightenment. I don't care _how_ a function
works, but _what_ it does. If I need the former, there is nothing that
works beside looking at the source - of course good comments ease the task
of understanding what's going on.

Diez