[Bf-taskforce25] Operator Naming Guidelines

[Brecht Van Lommel]

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.