[Bf-python] naming conventions, some propositions, and some misc reflexions...

[Willian Padovani Germano]

On Thu, 2003-06-19 at 10:49, Jacques Guignot wrote:
> Some propositions :
> 
> a) The C functions are prefixed with the module name, and underscore for 
> readability, followed by "get" or "set" and the name of the field (or 
> group of fields)
Already like this, ok.

> b) The corresponding python functions are the same, without the module 
> name :
Yes.

> c) Intern and helper functions : no rule
Maybe.  Even if they are static to avoid name clashing, there may still
be an issue with debuggers.  For example, running "gdb ./blender" I can
set a break point in function getSelectedFile (from Window.c) simply
with "break getSelectedFile"

If there was another function in Blender with this name, I haven't
tested what would happen.  And even if gdb provides some mechanism to
let us choose between possibilities, other debuggers might not.  So,
though I haven't done it myself yet, maybe it's better to prepend
something to intern functions, too, to help debugging.

> d) keywords for the "getattr" and "setattr" : use the names of the 
> fields in the corresponding C structure (they are generally well choosen)
These are the class member variables in Python, of course.  Here there
is that issue with compatibility, for older modules.  Sometimes we can
only use what the 2.25 API did.  And it's better to have understandable
names.  The ones in C structs aren't always very descriptive.

> e) in "getattr" and "setattr" : try to reuse the corresponding the 
> existing functions.
In setattr, yes, because it avoids reproducing the same piece of code
and keeps the setattr function smaller. In getattr ...

> counter example (sorry, Willian!) :
> if (strcmp(name, "name") == 0)
>     attr = PyString_FromString(self->camera->id.name+2);
: ), no need to apologize!

> f) I think that the speed factor should be considered as not very 
> important. It is crucial for guys working on rendering or computation of 
> the image. Not for us, an intepreter is not very fast by nature.
That's a deeper issue, like the security one, that, as you remember,
some considered unnecessary.  Personally I prefer to keep things "lean
and mean" when possible, specially in this case it's pretty trivial to
do it.

-- I'm just chatting for a few paragraphs:

Yes, exppython is scripting, it's slow.  But
1) That's not reason to make it even slower, much to the contrary, you
know.
2) We're not alone.  Exppython runs inside Blender, which runs on top of
some modern OS with quite a few other tasks going on.

Going a lot further to illustrate: imagine an artist running a script to
update his scene, while yafray or povray are rendering the previous try,
while he talks on #blenderchat about it and plays an mp3 or ogg all at
the same time, besides all his OS does in the background ... just check
the irc channel, this can happen.

The point is: we shouldn't make this decision for the user.  A gentle
program will run in more configurations, in older ones, in loaded ones,
much better than a bloated program.  I don't mean we should go all the
way to optimize every little corner, we are not even profiling /
optimizing.  It's just a part of how we program, our own way, let's
say.  I prefer to think about speed and memory, specially when it's
trivial to do so.  Besides, today programs are being run from pdas,
tomorrow cell phones maybe (?), then what?  Playing nice is as relevant
as always.

------------------------------ End of the chat

Back to real world coding.  I'm not saying people should program the way
I do (specially because I need the freedom to change my mind).  In this
particular case (the .name field in getattr), such a function won't be
called 2000 times in an inner loop, it's just a getName(), so I won't
ask you to optimize it to save a few cycles.

I believe we should leave some freedom for programmers in an open
project like this.  We'll follow Blender's coding guidelines, but those
are about code formatting, basically.  And it will be better to have
some naming convention for the different groups of functions, but that's
it.  Inside their functions, programmers should be free to follow their
own vision or else it won't be much fun to be in this project.

When there are bigger issues, then we discuss and change things, like we
have already done, sometimes from other suggestions you sent.  But in
cases like this one: you prefer to use the get functions in getattr, I
prefer not to, Michel used the Py* functions, too.  That's ok.

Open for discussion, as always.

There is an issue with that
>     attr = PyString_FromString(self->camera->id.name+2);
though.  The old bpython had interface files where these things (the
camera->id.name+2) were collected and encapsulated in macros.  It's a
wise thing to do, of course, because if that gets changed in Blender, we
only need to update one place.  Michel did it with functions, but in my
modules I used direct access.  This is not for now, but after 2.28, we
may isolate Blender specific (general, since ID is everywhere) things
like this in an interface file.

> g) Arguments : for compound objects (coordinates or color values for 
> instance) the "get" functions will rerturn a list. The "set" functions 
> will accept a list as argument.
Yes, this is simpler and better.  For new modules that's a good idea,
but for the old ones, we have to provide what the 2.25 API had, at least
now.  So I recall I made some function accept both: (f,f,f) or
([f,f,f]).

BTW, Guignot: Michel told me (and your msg confirms) that you are
writing the World module.  There's no need to follow its old API, from
Blender210.  You can go for consistency with the exppython way instead,
when you have to decide about py function names and vars, etc -- you can
consider it a new module.

--
Willian, wgermano at ig.com.br