are docstrings for variables a bad idea?

[Diez B. Roggisch]

jelle wrote:

> ---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.---
> 
> point taken. perhaps only variables declared in the __init__ should be
> made available as a doc string.
> 
> ---IMHO commenting the parameters and results of a function is what
> someone
> needs who skims the docs for enlightenment---

On a related note: for someone who's goal is more clarity in coding, your
style of quoting is thwarting that efforts.
 
> these are two completely different things:
> 
> f = instanceSomeClass() -> 'pops up the __init__ doc string in your
> IDE'
> 
> now, when this class is instanced, i think this could be useful:
> 
> f.someComplexMethod -> 'pops up the variable docstring'

I feared that you meant that - but wasn't sure. This is one of the
often-requested-yet-they-will-never-come features of IDEs for python, as
this would mean that you'd have type-information available on f. Consider
this simple example:

f = someRandomlyInstatiatedObject()

Now what is e.g. f.<C-space> to show? 

Additionally, if you typed f.foo yourself, is it foo of Foo, or foo of
FooSubclass, or foo of the totally unrelated Badabum?

> 
> I'm all for DRY -dont repeat yourself-, but DHORYEBNPTMTRYCEBPTSWTITDS
> -don't have others repeat your efforts by not providing the means to
> reuse your code efficiently by providing them sparsely with the
> information to do so-
> 
> could have some place in complex classes that are often subclassed.
> having the right information at the right time to do so would be quite
> a help.

This is sort of a tautology and applies to pretty much everything in life :) 

> be fair: do you perfectly well know how to subclass a class without
> (extensively) reading it back?

Sure you have to. but then you read the source.
 
> perhaps a variable doc here and there would make this slightly easier.

I'm still not seeing what you are really after. Python has no variable
declarations, so there is no natural point to put these, as it is e.g. in
JAVA. Gathering inline comments by some heuristics like "the following
statement has a assignment" might be feasible to implement, yet I fail to
see the usefulness for that, at least for methods in general.
 The exception from this would be the constructor, as sensible design
usually makes all instance variables known there - so something that
mangles

def __init__(self):
    # know where your foo is
    self.foo = 'here'

might be of interest. But then - it often enough happens that in some method
after some obscure logic some instance variable gets created.

Don't get me wrong: I'm all in favor of commenting code. But your wish for
semi-automatic doc-generation doesn't appeal to me. Now as I'm not the one
and only one to decide about this, if you come up with a reasonable
proposal how to document variables & how to make this available (in way
more technical terms than just "wouldn't it be nice to have") you might
convince some IDE-authors to adopt I gues.

Diez