[Bf-committers] Meeting minutes, june 27 2010

[Campbell Barton]

On Mon, Jun 28, 2010 at 3:48 AM, Matt Ebb <matt at mke3.net> wrote:
>
> On 28/06/2010, at 01:12 , Ton Roosendaal wrote:
>
>> - Campbell worked on proposals for naming properties, is a discussion
>> topic for this week.
>> http://wiki.blender.org/index.php/Dev:2.5/Source/Architecture/RNA#Naming_Conventions
>>  http://wiki.blender.org/index.php/Dev:2.5/Source/Architecture/RNA/Cleanup
>
> I see here there's a proposal to modify the names based on the type of data they represent (eg. use_ prefixes and _factor suffix). What's the reasoning behind this? It seems in several cases it makes the property names more verbose, awkward and less clear on what they actually do.
>
> For example there are some like use_clip that sound a bit weird because they're verbs - you don't "use clip" or "not user clip", you just "clip" or "not clip". Same for others like "use_active", by setting a boolean you want to say "it is active" or "it is not active", not "it is use active".
>
> There's also another issue with using the suffix "_factor" for any float with range 0.0-1.0. Factor literally means a multiplier, but this is not the right term to use in a lot of situations - even the given example of glossiness is not really a factor, it represents a continuum between fully rough and fully shiny, it's not anything that gets multiplied/scaled.
>
> Anyway, I understand if you want to make it consistent there will be times where it doesn't quite fit, but I'm wondering why this is really necessary at all to force it like this? Especially with python when you can inspect the data type already, and with RNA subtype info as well, do we really need to try and mark it in the property names too?
>
> cheers,
>
> Matt

Hi Matt,
What your posting is basically the reason that this topic is up for discussion.

I'm not dead-set on the current proposal but think we have to
compromise between consistency, correct description and brevity.

My aim is to come up with a set of rules we can follow most of the time.
This should be simple enough to follow when writing new api's and
consistent enough to be memorable.

The current use of *_factor seems awkward to me too, so Id be ok to
remove (need to go over entire API and make sure it doesn't give
problems, editing the booleans at the moment).

For use_*, this is a bit odd too but there are also many places where
we have names that would have a very different meaning without it eg.
 use_nodes use_alpha use_offset use_radius use_sharp

IMHO 'use_clip' is ok since clip could be a floating point like
clip_start, the alternative is not to use 'use_' prefix in ~half of
the property names which is bad for consistency :S.
Agree 'use_active' is not great, its not so simple since we have
active_render vs use_active_render..., need to look into this further.

I moved the draft from the wiki into svn so we can better track
suggested changes, Brecht has agreed to review this and make changes
(probably this week).

If your not happy with some of the decisions Id rather discuss these
on the mailing list or on IRC, instead of going in and editing
rna_api_cleanup.txt directly since its time consuming to make changes
back and forth.

- Campbell