Repository navigation
Method Stereotypes
A method stereotype is a concise high-level description of the role of a method in a software system. It is a simple form of documentation that is used to provide additional information about the behavioral aspects and responsibilities of a method. Method stereotype information can be used to lay the foundation of more sophisticated forms of documentations and design recovery [1][2].
Some uses of method stereotype information include improving the precision of metrics calculations [1], creating signature descriptors for software systems [2], measuring the level of improvement or degradation of a method when its role changes [3], improving feature location in source code [4], determining the stereotypes of classes [5], generating natural language summaries for methods [6], characterizing commits on version control systems into different types [7], enhancing object-oriented software comprehension [8], among many others.
Method stereotypes can be classified into five main categories depending on the role of a method. It is worth noting that a method can be labeled with one or more stereotypes from each category. Each stereotype below states the rule by which Stereocode assigns the stereotype, while the order of the rules and the groups of stereotypes that never appear together follow in the section How the Rules Combine. The section Data Members and Calls states what counts as a data member and how each call counts. One page per language, linked in the section Languages, gives the forms of these facts in that language. A method that fits no rule gets the stereotype unclassified.
| Stereotype Category | Stereotype | Description |
|---|---|---|
| Structural Accessor | get | Returns a data member |
| predicate | Returns Boolean value that is not a data member | |
| property | Returns non-boolean value that is not a data member | |
| void-accessor | Returns information about data members through parameters | |
| Structural Mutator | set | Modifies a data member |
| command | Performs a complex change to the object’s state. | |
| non-void-command | ||
| Creational | constructor | Creates and/or destroys objects |
| copy-constructor | ||
| destructor | ||
| factory | ||
| Collaborational | collaborator | Works with objects belonging to classes other than itself (parameter, local variable, data member, or return value) |
| controller | Changes only an external object’s state (not this) | |
| wrapper | Does not change an object’s state. Has at least one free function call | |
| Degenerate | incidental | Does not read/change an object’s state. Has no calls |
| stateless | Does not read/change an object’s state. Has at least one call to other class methods or to a free function | |
| empty | Has no statements |
TABLE 1. Taxonomy of Method Stereotypes.
A structural accessor is a method that returns information about the state of an object. There are four types: get, predicate, property, and void-accessor.
A get is a method returns the value of some data member
Stereocode labels a method get whatever its return type when one of these two conditions holds.
- A return expression is a data member alone, such as
return size;, or the value that a data member points to, such asreturn *size;. - A return expression is the object itself, such as
return *this;, and the method is no set, command, or non-void-command.
Examples for C++:
// @stereotype get
double AxisModelBase::getTickStep() const {
return m_tick_step;
}
// @stereotype get
bool RootBranch::isUseable() const {
return m_useable;
}Examples for C#:
// @stereotype get
protected override string GetSourceObjectEventName()
{
return _eventName;
}
internal string Namespace
{
// @stereotype get
get
{
return this.nameSpace;
}
}Examples for Java:
// @stereotype get
public final boolean isTimeout() {
return timeout;
}
// @stereotype get
long cachedEventCount() {
return size;
}A predicate is a method that computes a Boolean value using data member values and returns it.
Stereocode labels a method predicate when all three conditions hold.
- The return type is Boolean, such as
boolin C++ and C# orbooleanin Java. - A return expression is neither a data member alone nor the object itself, such as
return size > 0;. - The method uses a data member or calls an accessor of its class.
Examples for C++:
// @stereotype predicate
bool RootBranch::isMultiDimensional() const {
return !(m_number_elements == 1 );
}
// @stereotype predicate
bool RepBase::isSelected() const {
return m_desel == false;
}Examples for C#:
// @stereotype predicate
internal bool IsPassThruObjectNeeded()
{
return (_passThru) && (!this.DidUserSuppressTheOperation) && (!this.JobHadErrors);
}
// @stereotype predicate
internal bool HostInNestedPrompt()
{
if (NestedPromptCount > 0)
{
return true;
}
else
{
return false;
}
}Examples for Java:
// @stereotype predicate collaborator
public boolean hasThrowable() {
return done && error != null;
}
// @stereotype predicate collaborator
public boolean isOnComplete() {
return value == null;
}A property is a method that returns information (not Boolean) about an object using data member values.
Stereocode labels a method property when all three conditions hold.
- The return type is known and is neither void nor Boolean, where a
void*of C++ or C# counts as a returned value. - A return expression is neither a data member alone nor the object itself, such as
return size * 2;. - The method uses a data member or calls an accessor of its class.
// @stereotype property
double Range::fraction(double value) const {
return (value - m_min)/(m_max - m_min);
}
// @stereotype property
inline double Range::length() const {
return (m_max - m_min);
}Examples for C#:
// @stereotype property
public override string ToString()
{
return "LoadObject(" + (_value ?? "null") + ")";
}
// @stereotype property collaborator
internal int GetSessionsCount()
{
return this.curCimSessionsById.Count;
}Examples for Java:
// @stereotype incidental
public final int requestFusion(int mode) {
return mode & ASYNC;
}
// @stereotype property
int calcElementOffset(long index) {
return (int)index & mask;
}A void-accessor is a method that returns information about an object through a parameter.
Stereocode labels a method void-accessor when all three conditions hold.
- The return type is void, where a
void*of C++ or C# is no void. - The method writes through a parameter that shares its object with the caller, such as
out = size;for the C++ parameterint& out. - The method uses a data member or calls an accessor of its class.
Examples for C++:
// @stereotype void-accessor
inline void visible_cells(int& r1, int& r2, int& c1, int& c2) {
r1 = toprow;
r2 = botrow;
c1 = leftcol;
c2 = rightcol;
} Examples for C#:
// @stereotype predicate wrapper
internal bool IsFuzzyMatch(string candidate, string pattern, out int score)
{
score = GetDamerauLevenshteinDistance(candidate, pattern);
return score <= MinimumDistance;
}Examples for Java:
// @stereotype void-accessor
void dequantize(int[] dataUnit, int iComp) {
int[] qTable = quantizationTables[frameComponents[componentIds[iComp]][TQI]];
for (int i = 0; i < dataUnit.length; i++) {
int zzIndex = ZigZag8x8[i];
dataUnit[zzIndex] = dataUnit[zzIndex] * qTable[i];
}
}A structural mutator is a method that modifies the state of an object. There are three types: set, command, and non-void-command.
A set method is a mutator that modifies the value of a data member.
Stereocode labels a method set whatever its return type and its const specifier when all three conditions hold.
- The method changes exactly one data member, also where it writes that data member several times.
- No call on a data member and no call to a method of its class may change the object.
- The method does not write the whole object, as
*this = other;does.
Examples for C++;
// @stereotype set
void dataSource::setName(const string& name){
m_ds_name = name;
}
// @stereotype set
void ListTuple::setShape(std::vector<unsigned int>& shape) {
m_shape = shape;
}Examples for C#:
// @stereotype set
protected virtual void Dispose(bool disposing)
{
if (_disposed)
{
return;
}
_disposed = true;
}
internal TypeTable TypeTable
{
// @stereotype set collaborator
set { _serializer.TypeTable = value; }
}Examples for Java:
// @stereotype set
public void setDone()
{
this.done = true;
}
// @stereotype set
public void accept(Integer t)
{
items++;
}A command method is a mutator that modifies the state of an object in a complex way.
Stereocode labels a method command or non-void-command when the method changes the object in one of three ways.
- The method changes more than one data member or writes the whole object, as
*this = other;does. - The method changes one data member, while a call on a data member or a call to a method of its class may change the object.
- The method changes no data member, while a call on a data member or a call to a method of its class may change the object.
A C++ const method takes these stereotypes only in the first case, since such a method changes only mutable data members. The method is a command when it returns void or a return expression is the object itself. Any other such method is a non-void-command, where a Boolean and a void* count as returned values.
Examples for C++:
// @stereotype command
void DataSource::copyPrivate(const DataSource& other) {
m_ds_name = other.m_ds_name;
m_is_null = other.m_is_null;
m_labels = other.m_labels;
m_shape = other.m_shape;
m_title = other.m_title;
}Examples for C#:
public uint MaxEnvelopeSizeKB
{
// @stereotype command
set
{
maxenvelopesizekb = value;
maxenvelopesizekbSet = true;
base.SetParameter(value, nameMaxEnvelopeSizeKB);
}
}Examples for Java:
// @stereotype command collaborator
public void setup() {
flowable = Flowable.just(1);
observable = Observable.just(1);
single = Single.just(1);
maybe = Maybe.just(1);
completable = Completable.complete();
}A factory method is a creational method that creates an object and returns it to the client.
Stereocode labels a method factory when the two conditions hold.
- The return type is not primitive.
- A return expression creates an object, such as
return new Matrix(rows);, or returns a variable that the method assigns a created object, such asmadeafterMatrix* made = new Matrix(rows);.
Examples for C++:
// @stereotype factory stateless
CutRangeRep* CutRangeRep::clone() {
return new CutRangeRep(*this);
}
Examples for C#:
// @stereotype factory stateless
public LocalGroup Clone()
{
return new LocalGroup(this);
}Examples for Java:
// @stereotype factory wrapper stateless
public Processor<Integer, Integer> createIdentityProcessor(int bufferSize) {
UnicastProcessor<Integer> up = UnicastProcessor.create();
return new RefCountProcessor<>(up);
}Collaborational methods deal with objects of other classes. There are three types: collaborator, controller, and wrapper.
A collaborator method works on objects that belong to classes other than itself. These objects are usually passed as parameters, created as local variables, or accessed through some data member(s).
Stereocode labels a method collaborator when the two conditions hold.
- The method uses a type that is neither primitive nor its own class as the type of a parameter, a local variable, a data member, or the returned value, or the method returns a
void*in C++ or C#. - The method is no wrapper and no controller.
Examples for C++:
// @stereotype collaborator
void DisplayController::fixLogIfBinned ( const PlotterBase* plotter, DataRep* rep ) const {
setBinner ( plotter, rep, Axes::X );
setBinner ( plotter, rep, Axes::Y );
}
Examples for C#:
// @stereotype property factory collaborator
private LineOutput InstantiateLineOutputInterface()
{
PrinterLineOutput printOutput = new(_printerName);
return (LineOutput)printOutput;
}Examples for Java:
// @stereotype command collaborator
public void flowFlatMapIterable1(Blackhole bh) {
flowFlatMapIterable1.subscribe(new PerfConsumer(bh));
}A controller method only changes the state of external objects.
Stereocode labels a method controller when all four conditions hold.
- The method changes no data member and does not write the whole object.
- No call on a data member and no call to a method of its class may change the object.
- The method calls a method of another class, such as a method of a parameter, or changes a parameter or a local variable whose type is not primitive.
- The method is no wrapper.
Examples for C++:
// @stereotype controller
void BinnerAxisXML::setAttributes(XmlElement* tag, const BinnerAxis& binner ) {
const string & type = binner.name();
tag->setAttribute ( m_type, type );
const Range & range = binner.getRange ();
double high = range.high();
double low = range.low ();
tag->setAttribute ( m_high, high );
tag->setAttribute ( m_low, low );
double width = binner.getBinWidth ();
tag->setAttribute ( m_width, width );
}Examples for C#:
// @stereotype controller
public void TestClearContent()
{
FileSystemProvider fileSystemProvider = new FileSystemProvider();
ProviderInfo providerInfoToSet = GetProvider();
fileSystemProvider.SetProviderInformation(providerInfoToSet);
fileSystemProvider.Context = new CmdletProviderContext(GetExecutionContext());
fileSystemProvider.ClearContent(testPath);
Assert.Empty(File.ReadAllText(testPath));
}Examples for Java:
// @stereotype controller
void subscribe(Flowable<Integer> f, Blackhole bh) {
PerfAsyncConsumer consumer = new PerfAsyncConsumer(bh);
f.subscribe(consumer);
consumer.await(count);
}A wrapper method does not change an object’s state and has at least one free function call. A call on another object makes the method a controller instead.
Stereocode labels a method wrapper when all four conditions hold.
- The method changes no data member and does not write the whole object.
- No call on a data member and no call to a method of its class may change the object.
- The method calls no method of another class.
- The method calls at least one free function, where a creation with
newcounts as no call.
Examples for C++:
// @stereotype wrapper
void OpenGLWindow::flush()
{
glFinish();
glXSwapBuffers(m_display,m_window);
}Examples for C#:
// @stereotype wrapper
protected virtual void Dispose(bool disposing)
{
if (disposing)
{
File.Delete(testPath);
}
}Examples for Java:
// @stereotype wrapper
public void onSubscribe(@NonNull Disposable d) {
DisposableHelper.setOnce(upstream, d);
}A degenerate method is a method that has no use of the object's state. There are three types: incidental, stateless, and empty[8]
An incidental method is a method that does not read or change an object’s state and has no calls.
Stereocode labels a method incidental whatever its return type when all three conditions hold.
- The body holds a statement other than a comment.
- The method uses neither a data member nor the object itself.
- The method makes no call of any kind, a creation with
newincluded.
Examples for C++:
// @stereotype incidental
bool NTupleChiSqFCN::needsIntegrated() const {
return false;
}
Examples for C#:
// @stereotype incidental
protected override string GetSourceObjectEventName()
{
return "CimIndicationArrived";
}Examples for Java:
// @stereotype incidental
public long maxElementsFromPublisher() {
return 1;
}A stateless method is a method that does not read or change an object’s state directly. This method has at least one call to other class methods or to a free function.
Stereocode labels a method stateless whatever its return type when all four conditions hold.
- The body holds a statement other than a comment.
- The method uses neither a data member nor the object itself.
- No call on a data member and no call to a method of its class may change the object.
- The method calls a free function, calls a method of another class, or creates an object with
new.
Examples for C++:
// @stereotype wrapper stateless
virtual double errorDef () const {
return up();
}
Examples for C#:
// @stereotype command
public override void EnterNestedPrompt()
{
EnterNestedPrompt(null);
}Examples for Java:
// @stereotype controller stateless
public void successDetaches() throws Exception {
Disposable d = Disposable.empty();
final WeakReference<Disposable> wr = new WeakReference<>(d);
TestObserver<Integer> to = new Maybe<Integer>() {
@Override
protected void subscribeActual(MaybeObserver<? super Integer> observer) {
observer.onSubscribe(wr.get());
observer.onSuccess(1);
observer.onSuccess(2);
};
}
.onTerminateDetach()
.test();
d = null;
System.gc();
Thread.sleep(200);
to.assertResult(1);
assertNull(wr.get());
}An empty is a method that has no statements (except for comments).
Stereocode labels a method empty when its body holds no statement other than comments. An empty method gets no other stereotype, since this rule comes before every other rule except the rules of constructors and destructors. The language pages state what else an empty body may hold, such as pass in Python.
Examples for C++:
// @stereotype empty
void hippodraw::Observer::willDelete(const Observable*) {
// do nothing, default behaviour
}Examples for C#:
// @stereotype empty
internal virtual void RemoveCommandTransportManager(Guid powerShellCmdId)
{
}Examples for Java:
// @stereotype empty
public void onSubscribe(Disposable d)
{
}Stereocode applies the rules of the method stereotypes in a fixed order and gives a method every stereotype whose rule holds. A constructor, a copy constructor, and a destructor get the stereotype of their kind alone, namely constructor, copy-constructor, or destructor. A copy constructor is a constructor whose first parameter takes an object of its own class, such as Matrix(const Matrix& other). An empty method gets no other stereotype either. The other rules follow in the order of the output, from get to stateless. A method that satisfies none of these rules gets the stereotype unclassified.
Several stereotypes can hold for one method, such as get with collaborator or property with factory and collaborator. However, the conditions of the rules allow at most one stereotype of each of these groups.
- predicate, property, and void-accessor, since their rules require a Boolean return type, another returned value, and a void return type.
- set, command, and non-void-command, since set requires exactly one changed data member without a call that may change the object, while each case of the command rules excludes this combination.
- wrapper, controller, and collaborator, which Stereocode tests in this order.
- incidental and stateless, since incidental requires a method without calls and stateless requires a call.
The rules count the object itself, such as this or *this alone, as a use of a data member. A call to a method of the class or of a parent class in the archive and a call on a data member whose class is in the archive count by the stereotypes of the methods that the call may reach. These methods are the methods of its name that take its number of arguments, as the section Data Members and Calls states. A reached accessor makes the call a read of the object. Such a read counts as a use of a data member. The call may change the object when a reached method is a set, a command, or a non-void-command, when a reached method is neither an accessor nor a degenerate method, or when no method with stereotypes fits the call. A read through whose result the code writes, as at(i) = x does, may change the object as well. A call that reaches only degenerate methods counts as a call of a free function. For a recursive call, the calling method counts by the stereotypes that the method has without such calls.
Stereocode first classifies each method with each such call counted as a call that may change the object. It then classifies again the callers of each method whose stereotypes changed, until no stereotype changes or 100 rounds have passed. The stereotypes therefore do not depend on the order of the methods in the archive.
The rules above hold in every language, while the facts that the rules test take the forms of each language. One page per language, namely C and C++, C#, Java, Python, and JavaScript and TypeScript, gives these forms in full, together with the built-in lists of Stereocode and a labeled example of each stereotype. Table 2 compares the main forms.
| Fact | C and C++ | C# | Java | Python | JavaScript and TypeScript |
|---|---|---|---|---|---|
| Object |
this, *this
|
this |
this |
First parameter, such as self
|
this |
| Boolean return types |
bool, _Bool
|
bool, Boolean, System.Boolean
|
boolean, Boolean, java.lang.Boolean
|
bool |
boolean, Boolean
|
| Void return types | void |
void, Void
|
void, Void
|
None |
void, undefined, never
|
| Creation of an object | new |
new |
new |
Call of a class | new |
| Parameters shared with the caller | References, pointers, and arrays |
ref, out, and class types |
Types that are not primitive | Parameters without a primitive annotation, except *args and **kwargs
|
Parameters without a primitive annotation, arrays, tuples, and object types, except ...rest
|
| Section of the list files | [C++] |
[C#] |
[Java] |
[Python] |
[JavaScript] |
TABLE 2. Forms of the facts of the rules in each language.
Each rule of this page reads facts about a method, namely the data members that the method uses or changes, the types of its variables, the values that it returns, and the calls that it makes. Stereocode determines these facts by the conventions of this section in every language. A language page replaces or adds to a convention where its language takes another form, such as the undeclared data members of a Python class.
- The data members of a type are its fields and the fields of each parent type that the archive defines.
- A static field counts as a global variable for reads and writes alike. A method that uses only static fields therefore uses no state of the object.
- The object itself passed to a constructor, as in
new A(this)orBinder binder(*this);, uses no state of the object.
- Where classes of one name in several folders fit a type name equally well, as the implementations of one class for several platforms do, the type name refers to each of these classes. A call on a data member of that type reaches the methods of each class.
- A qualified type name, such as
Connection.Requestorwire::Request, names the own type only where its qualifiers agree with the namespace, the package, or the enclosing types of the own type. - Stereocode compares the type of an inherited data member with the class of the method that uses the member. A data member
nextof the typeNode, declared in the classNode, therefore makes a method of its child classElementthat usesnexta collaborator.
- A cast before a whole returned expression is ignored.
return (Node) next;thus returns the data membernext. - A returned container keeps its whole type, which is neither Boolean nor void. A method
List<Boolean> active()therefore gets the stereotype property, while a return typebool?of C# orBooleanof Java stays Boolean. - An element of a created array or collection is no created object. A method that returns
made[0]afterMatrix[] made = new Matrix[rows];therefore gets no factory.
- A call reaches every method of its name that takes its number of arguments. Where none takes that number, the call reaches every method of its name. A call of a virtual method counts by the method that it names, without the methods that override that method.
- Where only methods declared without a definition, such as abstract methods, take the number of arguments of a call, the call reaches no method with stereotypes. Such a call may therefore change the object. The same applies where no method of its name takes its number of arguments while the type has a parent outside the archive.
- A call to the object itself, written through
thisor without an object, is a call of a static method where no instance method of its name takes its number of arguments while a static method of that name does. Such a call counts as a call of a free function. - A call to the object itself whose method no type of the archive defines reads the object in two cases. First, the method is an accessor of the root class of its language, such as
toStringofObjectin Java. Second, the method is a query method while the type has a parent outside the archive. Any other such call may change the object. - A call on a data member counts by the methods that it reaches when the type of the data member is a type of the archive, such as
items.add(x)for a data memberitemsof a classItemListof the archive. A call on a data member of a type outside the archive may change the data member. - A call on an element of a variable, such as
slots[i].clear()of a data member orothers[0].clear()of a parameter, is a call on that variable. The declaration of the variable gives the type of its elements, such asSlotofSlot[],Slot*, orstd::vector<Slot>. - A query method only reads the data member that it is called on. Each language page lists the built-in query methods of its language. The option
-qadds query methods. - The rules ignore the calls that only report or end the program, such as
assertin C++ orSystem.exitin Java. Each language page lists these calls. The option-cadds calls to ignore. - A call through the name of a type, such as
File.Delete(path)in C# orMath.max(a, b)in Java, counts as a call of a free function. - A call on a parameter, on a local variable, or on the result of another call, such as
test()inFlowable.just(1).test(), is a call on another object. - A call of a variable, by its name or through the call operator of its language, such as
callback()of a parameter,operator()in C++, orInvokein C#, runs the function that the variable holds. The call reads the variable and counts as a call of a free function. A variable whose type is a class of the archive holds an object instead. A call of such a variable counts as a call to the call operator of that class. - The code of a lambda and of a local or nested function, such as a C# local function, a Python nested function, or a JavaScript arrow function, counts as code of the enclosing function. A
returninside such code returns no value of that function. The rules ignore a call of a local or nested function by its name, since its code already counts. - A constructor call with
newcounts toward factory and stateless. The rules of wrapper and controller leave such a call out, while a method with such a call is never incidental. Each language page states the other forms of a constructor call in its language, such asstd::make_uniquein C++. - A method of the own type named without a call, such as
Start(OnWorkFinished)in C#,this::processin Java, orself.on_donein Python, is no call and no use of the object. A method reference of a data member, such asitems::add, reads the data member.
[1] Dragan, N., Collard, M. L., & Maletic, J. I. (2006, September). Reverse engineering method stereotypes. In 2006 22nd IEEE International Conference on Software Maintenance (pp. 24-34). IEEE.
[2] Dragan, N., Collard, M. L., & Maletic, J. I. (2009, September). Using method stereotype distribution as a signature descriptor for software systems. In 2009 IEEE International Conference on Software Maintenance (pp. 567-570). IEEE.
[3] Decker, M. J., Newman, C. D., Dragan, N., Collard, M. L., Maletic, J. I., & Kraft, N. A. (2018, May). A taxonomy of how method stereotypes change. In Proceedings of the 40th International Conference on Software Engineering: Companion Proceeedings (pp. 337-338).
[4] Alhindawi, N., Dragan, N., Collard, M. L., & Maletic, J. I. (2013, September). Improving feature location by enhancing source code with stereotypes. In 2013 IEEE International Conference on Software Maintenance (pp. 300-309). Ieee.
[5] Dragan, N., Collard, M. L., & Maletic, J. I. (2010, September). Automatic identification of class stereotypes. In 2010 IEEE International Conference on Software Maintenance (pp. 1-10). IEEE.
[6] Abid, N. J., Dragan, N., Collard, M. L., & Maletic, J. I. (2015, September). Using stereotypes in the automatic generation of natural language summaries for c++ methods. In 2015 IEEE International Conference on Software Maintenance and Evolution (ICSME) (pp. 561-565). IEEE.
[7] Dragan, N., Collard, M. L., Hammad, M., & Maletic, J. I. (2011, September). Using stereotypes to help characterize commits. In 2011 27th IEEE International Conference on Software Maintenance (ICSM) (pp. 520-523). IEEE.
[8] Gökmen, R., Heidrich, D., Schreiber, A., & Bichlmeier, C. (2021, August). Stereotypes as design patterns for serious games to enhance software comprehension. In 2021 IEEE Conference on Games (CoG) (pp. 1-3). IEEE.