[Bf-taskforce25] Operator Naming Guidelines

[Ton Roosendaal]

Hi,

> * Get rid of OT in the name (what's the purpose?).

I choose the operator names in C this way so they visually distinct 
well from defines or other API function calls. My text editor allows 
showing a list of function calls, and this way I can quickly browse to 
operator code. See the confusement that could happen otherwise:

"WM_OT_exit_blender"

or

"WM_exit_blender"

What I proposed to Campbell is to parse such operator names, and strip 
off the first part including the OT, and put those in modules together;

wm.exit_blender()

-Ton-

------------------------------------------------------------------------
Ton Roosendaal  Blender Foundation   ton at blender.org    www.blender.org
Blender Institute BV  Entrepotdok 57A  1018AD Amsterdam The Netherlands

On 29 Dec, 2008, at 9:44, Brecht Van Lommel wrote:

> Hi,
>
> Campbell Barton wrote:
>> docs for bpyoperator
>> http://www.graphicall.org/ftp/ideasman42/html/bpyoperator-module.html
>
> Great to see the python API moving along so fast, though this docgen
> does show the inconsistent operator naming pretty clearly. So here are
> some proposed guidelines that could be followed. They would require
> quite a few changes though so don't start renaming yet, this is just a
> proposal. The main changes I'm proposing are:
>
> * Get rid of OT in the name (what's the purpose?).
> * Always used a verb in the name.
> * Consistent order of verb and subject in the name.
>
> What I wrote down here turned out a bit long, but I imagine that once
> existing operator names are consistent it should all be clear from
> example anyway.
>
> Proposed Guidelines
>
> CATEGORY_some_name
> Some Name
>
> * CATEGORY: full upper case without underscores, indicating the
> category of the operator. Using abbreviations is permitted, however
> only start doing that when the full word is longer than about 6
> characters (a bit longer is permitted too). Examples: ACTION, ANIM,
> VIEW2D, WM
>
> * There was some talk about registering prefixes for plugins and
> extension, i.e. all renderman related tools with a RMAN_ prefix or so.
> However the CATEGORY_ would contain the subject often, so perhaps that
> should be a separate prefix, not part of the name for the user
> interface or scripts but part of the unique identifier, e.g.
> VERSE_OBJECT_upload.
>
> * some_name: is full lower case with underscores to separate words.
> Examples: toggle_time, change_frame, circle_select.
> * Separate words with an underscore if they cannot be considered a
> single word. I.e. selectall should be select_all. However borderselect
> or ipotype could be considered a single word, though in these cases I
> would edge on using an underscore.
>
> * From the CATEGORY we can already assume what we are working with,
> and that does not need to be repeated in the name. For example
> VIEW2D_zoom and VIEW3D_zoom are valid names, it is not needed to write
> VIEW2D_view_zoom.
>
> * Try to avoid cryptic names and abbreviations, e.g. cfrasnap,
> expotype, homefile.
>
> * Should the name always contain a verb? I.e. VIEW3D_clipping and
> SCREEN_screen_full_area could be changed to VIEW3D_set_clipping and
> SCREEN_toggle_full_area. I prefer to have "set_" and "toggle_" in
> there for consistency even if it could perhaps be left out.
>
> * Often the name will contain both a verb and a subject but the order
> of those is currently not consistent.
>    * subject_verb: keyframes_border_select, previewrange_clear.
> Advantage is that it is easier to see categories, i.e. all the
> keyframes_ prefixes make the subject immediately clear, however it is
> debatable if we should have the prefix in the first place and cannot
> use the CATEGORY to make this distinction.
>    * verb_subject: repeat_last, circle_select_keyframes, change_frame.
> An advantage is that it is a more correct english sentence and so
> better corresponds to the names used in the UI, so I prefer this form.
>
> * Some Name: is a more human readable name with spaces and all words
> capitalized. It should generally correspond closely to the some_name,
> to make it easy for users to see the correspondence between tools and
> scripts. This name can in most cases be equal to the name used in the
> menu.
>
> Brecht.
> _______________________________________________
> Bf-taskforce25 mailing list
> Bf-taskforce25 at blender.org
> http://lists.blender.org/mailman/listinfo/bf-taskforce25
>