Repository navigation
Free Function Stereotypes
A free function is a function that is not bound to a particular class. Static methods/functions as well as friend functions (C++) are also considered as free functions.
| Type | Description |
|---|---|
| predicate | Returns a bool derived from the parameters |
| property | Returns a non-bool derived from the parameters |
| global-command | Changes a global or a static variable, by a write or by a call on the variable other than a query method |
| command | Changes a parameter that shares its object with the caller, by a write through the parameter or by a call on the parameter other than a query method |
| factory | Creates an object with new, std::make_unique, or std::make_shared and returns the object |
| main | A main function, such as main, Main, wmain, WinMain, wWinMain, _tmain, or _tWinMain |
| literal | Does not read or change parameters, globals, or static variables |
| wrapper | Does not change a parameter that shares its object with the caller. Has at least one call to methods of other types or to a free function |
| empty | Has no statements |
| unclassified | Fits none of the rules |
TABLE 1. Taxonomy of Free Function Stereotypes.
Stereocode labels free functions and static methods only with the option -f. Each language page states which functions count as free functions, such as a function among the top-level statements of a C# program. A main function and an empty function get no other stereotype, while a function can carry several of the other stereotypes, such as predicate wrapper.
A returned value is derived from the parameters when the function uses a parameter and a return expression returns a parameter or computes a value, such as return a < b; or return found;.
Whether a parameter shares its object with the caller depends on the forms of its language, such as a C++ reference to an object that is not const or a Java parameter of a type that is not primitive. Table 2 of the method stereotypes compares these forms, while each language page states them in full. The conventions of the section Data Members and Calls on types, returned values, and calls hold for free functions as well, such as the query methods and the ignored calls.
Each rule below states the conditions under which Stereocode assigns its stereotype, in the order in which Stereocode applies the rules. A function that satisfies no rule gets the stereotype unclassified. Each example comes from the labeled case test/stereotypes/c/free_functions.c, except the example of factory from test/stereotypes/cpp/free_functions.cpp, since C creates no object with new.
A function named main, Main, wmain, WinMain, wWinMain, _tmain, or _tWinMain is a main function, whatever its body holds. This rule comes first. A main function gets no other stereotype.
// @stereotype main
int main(void) { bump(); show(twice(zero())); return 0; }A function whose body holds no statement other than comments is empty. An empty function gets no other stereotype.
// @stereotype empty
void noop(int value) { }A function is a predicate when its return type is Boolean and its returned value is derived from the parameters, as the paragraphs above the rules define.
// @stereotype predicate
bool is_origin(const struct point* p) { return p->x == 0 && p->y == 0; }A function is a property when its return type is known and is neither void nor Boolean while its returned value is derived from the parameters. A void* of C++ or C# counts as a returned value.
// @stereotype property
static int twice(int v) { return 2 * v; }A function is a global-command when it changes a global variable or a static variable, such as a static data member of a class or a static local variable.
// @stereotype global-command
void bump(void) { counter++; }A function is a command when it changes a parameter that shares its object with the caller.
// @stereotype command
void set_x(struct point* p, int x) { p->x = x; }A function is a factory when its return type is not primitive and a return expression creates an object with new or returns a variable that the function assigns such an object.
// @stereotype property factory
Widget* makeWidget(int style) { Widget* widget = new Widget(style); return widget; }A function is a literal when it uses no parameter, no global variable, and no static variable.
// @stereotype literal
static int zero(void) { return 0; }A function is a wrapper when it changes no parameter that shares its object with the caller and makes at least one call, where a creation with new counts as no call.
// @stereotype wrapper
void show(int v) { printf("%d\n", v); }