[Tutor] assigning __doc__ strings (manually)

[Brian van den Broek]

Hans Fangohr said unto the world upon 2004-09-01 17:21:
> Greetings,
> 
> I am facing the following problem and would like some advise:
> 
> I have two functions, say for simplicity, real_f and f:
> 
> def real_f(x):
>     """this is my doc-string"""
>     return x**2, x**3
> 
> def f(x):
>     return real_f(x)[0]
> 
> 
> The actual work is done in real_f() and some users might be interested
> in x**3 and x**2. However, most of the users will only care about x**2
> and are happy to use the function f() for this.
> 
> (In the actual program I am working on there is of course more work
> involved than just computing x**2 and x**3 ...)
> 
> Since the main computation is done in real_f(), I thought I'd create a
> doc-string in real_f() that explains the computation being implemented
> etc (as done above).
> 

<SNIP>

> Hans
> 

Hi Hans,

I get that your code description was simplified, but I've a question and
possibly a suggestion about it. (All this is orthogonal to your posted
question.)

 From what you say, it seems like you are expecting most of the time the
function f() will be the one used, and real_f() will be directly called
much less often. As you describe your setup, f() essentially runs real_f()
and throws away half the work it produces. (Are there needed side-effects
to the "thrown-away" part of real_f() that you didn't mention?)

In that context, wouldn't it be more efficient to put the computational
work in f() directly and have real_f() call f() and then itself do the
other needed work?

I mean something like

def f(x):
	return x**2

def real_f(x):
	return f(x), x**3

(Obviously the names you posted are no longer the ones to use in that f()
now really does something itself, but I'm keeping your names structure.)

It won't matter much for such simple computations as the toy ones of your
post, and I get the "premature optimization is the root of all evil"
point. But still, to this relative newcomer's mind, your structure seems
undesirable.

So, this is either a request for an explanation of what is wrong with what
I say, or a helpful observation. I leave it to those higher up the
pythonic peaks to determine which ;-)


Best to all,

Brian vdB