[Tutor] class method problem

[Steven D'Aprano]

On Sun, 26 Sep 2010 02:26:25 pm David Hutto wrote:
> On Sat, Sep 25, 2010 at 9:16 PM, Steven D'Aprano <steve at pearwood.info> 
wrote:
> > On Sun, 26 Sep 2010 08:13:23 am David Hutto wrote:
> >> Since I had nothing else to do, but practice, this looks much
> >> better:
> >>
> >> def find(word, search):
> >>       if search in word:
> >>               print True
> >>       else:
> >>               print False
[...]
> OP wanted to find if a in b. Does my function do that?...Yep

I didn't say that the function did the wrong thing, I said the name was 
misleading for what it actually did.

Why didn't you call the function len(), or deleteItemsFromPage()? 
Because those names would be misleading, deceptive and silly. And so is 
calling a function find() when it does something completely different 
from the commonly understood meaning of the word "find".

When you find something, you know where it is afterwards. In the context 
of text searches, that means returning an offset to where the target is 
found, or something similar. That's what str.find() does, and regular 
expressions, and list.index(). Your "find" function is a membership 
test, which is what the `in` operator is for.




> >    Yes, we found your terms on the Internet, but we won't tell you
> >    where. If you would like to find something else, we won't tell
> >    you where that is either.
>
> It's not supposed to be a four line version of Google.

I didn't say it was. I tried to inject a little humour into the email, 
but it clearly didn't work.


[...]
> > Even this is slightly misleading, because "text" doesn't need to be
> > an actual string. It could be any sequence, such as a list. But
> > this gives the *intention* of the function, which is to do text
> > searches. So this is (in my opinion) an acceptable compromise
> > between intention and generality.
>
> Semantics, are only important to those who didn't write it.

"Semantics" means "meaning". If you are trying to tell me that the 
meaning of programs -- their *purpose* -- is unimportant, that it 
doesn't matter what a function does, I'm afraid you'll have your work 
cut out to convince me.

The most important reader of your functions is... you. The function 
might be fresh in your mind *today*, but tomorrow? Next week? Six 
months from now when you discover a bug in your program and are trying 
to remember how it works so you can fix it?

Trust me, any non-trivial program that you don't just use once and throw 
away needs to be written with a careful eye to naming functions and 
arguments. The ideal is that you should never need to write 
documentation, because the functions and arguments document themselves. 
(This is an ideal that never quite works in practice, but we can at 
least *try*.)

An excellent piece of advice I've been given is to write your program's 
API -- the names of functions, the calling signatures, and so forth -- 
as if the next person to maintain that code will be a psychopath with a 
hair-trigger temper and a gun and who knows where you live. Since the 
next person to maintain it will likely be you, you will save *much* 
more time in the future by careful and consistent naming than it costs 
to think of those names right now.



-- 
Steven D'Aprano