User:Jon Denning/Projects/Function Naming

Intro to this Doc
I created this document as a simple guide to help me understand how functions are currently named and called, especially since some functions rely heavily on many levels of indirect calling. Presently, this document is only based on my experience and understanding and some feedback, so it likely contains errors.

I have two hopes for this document:


 * after being reviewed, corrected, and improved, that this document could be made available to newcomers as part of their onboarding, and
 * this document could morph into a function naming design doc

Notes: This is far from exhaustive or comprehensive, as I have only explored a small subset of the codebase. Also, this is (mostly) my understanding of the code base, which could be incorrect.

Let me know if you find bugs or other ways to improve this document!

General

 * A `static` function is only accessible within that file (limited scope, not a "global" function, which is the default). While this qualifier is not part of the function's name, it is still useful to know for understanding the scope of functions.


 * Naming should follow the `snake_case` convention.


 * Different areas of code may adopt different coding styles, so prefixes and suffixes may not be correct or consistent.


 * Many of these conventions will (hopefully!) change as Blender moves away from C and toward C++ (yay, namespaces!).

Other Links
Always refer to official documentation. Listed below are some great starting places.


 * Blender Code Documentation
 * C/C++ Style Guide

Maths
The mathematics code has its own naming convention.

Vectors
Vector functions have a prefix that indicates what operation is performed, a possible infix and 1+ suffixes to indicate vectors. The first vector passed (whether infix or suffix if no infix) is usually considered the destination, and the second vector passed (if applicable) is considered the source. If three or more vectors are given in total, the first is the destination, and the other two are sources.

Due to the limitations of C (no function overloading), a final suffix could be added to indicate that the vector types are `double` (`db`), `int` (`i`), `short` (`short`), etc. If no type is given, `float` (`fl`) is assumed.

Note: a singleton vector (a single `float`) is denoted with `i`, `fl`, or `db`.

Prefixes
Some general notes follow.


 * If the function begins with a capitalized letter, these functions should be considered as "public" and therefore part of the Blender API (callable from other parts of Blender code).

Modules-ish
Module prefixes can be in all caps (indicating public functions), but not always. A module prefix indicates the module to which that function "belongs" (see Modules).

The following list includes modules as well as subprojects, subareas, and other module-like groups of functions.

Comments:


 * I'm not sure what distinguishes the `EDBM_*` fns differ from the `BM*` / `BM_*` fns, other than the BMesh fns are low level while the `EDBM` fns are higher (calling the BMesh fns) and work to maintain correspondence between edit mesh and bmesh.

Non-modules
Non-module prefixes give indication as to how or why the function is called. Groups of functions can adopt a local prefix (only used in a single file or small number of files) to show their relation (ex: `raycast_*` in `raycast_all_cb`, `raycast_tri_backface_culling_test`, and `raycast_obj_fn`). The table below covers only the prefixes that are broadly adopted.

Operators
Operators are groups of functions with the same base function name that all work together to perform some operation. The suffix indicates what part that function performs for the overall operation.

Note: this follows the BPY `Operator` naming conventions. See `wmOperatorType`.

Non-operators
Comments:


 * Should `get` be a final suffix as in `*_color_get`, or should it be a verb of the suffix as in `*_get_color`?