Linguistic Anti-patterns (LAs) are inconsistencies between the signature (e.g., name, type), documentation (e.g., comments), and implementation of an entity (method or attribute). LAs are considered poor practices as when reading for example a method name, one may suppose a behaviour of the method that is different from the actual one.
List of Linguistic Anti-Patterns (LAs)
A1: Method get does more than returning the corresponding attribute.
A2: Method name is predicate but return type is not Boolean.
A3: Method set returns.
A4: Method type suggests multiple objects but name suggests single object.
B1: Method comments document a not implemented condition.
B2: Method performing validation does not return.
B3: Method name suggests that an object will be returned but the return type is void.
B4: Method name is predicate but nothing is returned.
B5: Method transforming an object does not return the transformed object.
B6: Method type indicates single object but the name indicates multiple objects.
B7: Method get does not return the corresponding attribute.
C1: Method name and type use antonyms, i.e., words with opposite meaning.
C2: Method comments and signature use antonyms, i.e., words with opposite meaning.
D1: Attribute type suggests multiple objects but the name suggests single object.
D2: Attribute name is predicate but type is not Boolean.
E1: Attribute type suggests single object but the name suggests multiple objects.
F1: Attribute name and type use antonyms, i.e., words with opposite meaning.
F2: Attribute comments and signature use antonyms, i.e., words with opposite meaning.
Details: Accessor methods, also called getters, provide a way to access class attributes. As such, it is not common that getters perform actions other than returning the corresponding attribute. Any other action should be documented, possibly naming the method differently than getSomething.
Inconsistency between: method name (starts with “get”) and implementation (perform actions other than returning the corresponding attribute without documenting it).
Exceptions: Lazy loading, Singleton design pattern.
Details: When a method name starts with the term “is” one would expect Boolean as a return type. Thus, having an is method that does not return Boolean, but returns more information, e.g., a wider range of values, is counterintuitive. In such cases, the method should be renamed or, at least, the fact that it returns a different type should be documented in the method comments.
Inconsistency between: method name (starts with “is”) and return type (type, other than Boolean, without documenting the return values).
Details: Modifier methods, also called setters, are methods that allow assigning a value to a class attribute (normally protected or private, hence not directly accessible from outside). By convention, setters do not return anything. More generally, the same statement is valid for methods whose name starts with “set”. Thus, to avoid any misuse, a set method having a return type different than void should document the return type/values with an appropriate comment.
Inconsistency between: method name (starts with “set”) and return type (other than void, without documenting the return type and values).
Details: When a method name indicates that a single object is returned, this should be consistent with its return type. If, instead, the return type is a collection, the method should be renamed or appropriate documentation is needed. An example of this LA is method getName returning Vector.
Inconsistency between: method name (suggests that a single object is returned) and return type (a collection, without documenting the return type).
Details: Method comments suggest a conditional behavior that is not implemented in the code. Clients of this method will thus wrongly assume the method behavior. Such inconsistency, if designed by purpose (e.g., conditional behavior is to be implemented by subclasses), should be at least documented.
Inconsistency between: method comments (suggest conditional behavior) and implementation (no conditional statement).
Details: A validation method does not confirm the validation, i.e., the method neither provides a return value informing whether the validation was successful, nor documents how one should proceed to understand. Very likely, such an outcome is stored somewhere — e.g., in an instance variable — however this does not result clear from the method documentation.
Inconsistency between: method name (suggests that a validation will be performed) and return type (void, without documenting how to understand whether the validation process was successful).
Details: The name suggests that the method returns something (e.g., getSomething, returnSomething), however this is not the case. One would expect to be able to assign the method return value to a variable, however this is not possible. Therefore, one has to further understand the source code to determine where the resulting data is stored and how to obtain it.
Inconsistency between: method name (suggests something will be returned) and return type (void, without documenting where the result is stored).
Exceptions: For large data it is common to modify one of the parameters rather than return it, however this should be clear from the naming of the parameter and the documentation.
Details: The method name is in the form of predicate whereas the return type is not Boolean. One would expect to be able to assign the result of such method to a variable or to use it in a control structure. However, this is not possible. One such example is method isValid with return type void.
Inconsistency between: method name (predicate) and return type (void, without documenting where the result is stored).
Exceptions: Modifiers to attributes of type Boolean are named starting with “is” rather than “set”.
Details: The method name suggests the transformation of an object (e.g., toString), but there is no return value. One would expect to be able to use the result of such method. However, this is not possible and it is not clear from the documentation where the result is stored.
Inconsistency between: method name (suggests a transformation) and return type (void, without documenting where the result is stored).
Exceptions: For large data it is common to modify one of the parameters rather than return it, however this needs to be clear from the naming of the parameter and the documentation.
Details: The method name suggests that a collection should be returned (e.g., getStatistics). However, a single object (e.g, Boolean), or nothing, is returned.
Inconsistency between: method name (suggests that a collection will be returned) and return type (void or a type that is not a collection).
Details: Accessor methods, also called getters, provide a way to access class attributes. As such, it is not common that getters do not return the corresponding attribute. The method should be possibly renamed or the attribute should be returned.
Inconsistency between: method name (starts with “get”) and implementation (does not return the corresponding attribute).
Details: The intent of the method suggested by its name is in contradiction with what it returns, e.g., the method named disable has a return type ControlEnableState. The inconsistency comes from the words “disable” and “enable” – have opposite meanings.
Inconsistency between: method name and return type – they contain terms that have opposite meanings, i.e., antonyms.
Details: The documentation of a method is in contradiction with its declaration (e.g., name, return type). For example, method isNavigateForwardEnabled is in contradiction with it’s comment documenting “a back navigation”, as “forward” and “back” are antonyms. Such inconsistency may be misleading as one is unsure whether to trust the comment or the method signature.
Inconsistency between: method signature (e.g., name, type) and documentation – they contain terms that have opposite meanings, i.e., antonyms.
Details: An attribute name suggests a single instance, while its type suggests that the attribute stores a collection of objects. For example attribute named target of type Vector. One may not know if a change to the attribute affects one or multiple instances in the collection.
Inconsistency between: attribute name (suggests a single object) and declared type (a collection of objects without clarifying documentation).
Details: An attribute name suggests that its value is true or false, but its declaring type is not Boolean. For example, attribute named isReached of type int[].
Inconsistency between: attribute name (suggests a true/false value) and declared type (not a Boolean, and the documentation does not explain the valid values).
Exceptions: Use int instead of Boolean where 0 corresponds to false and 1 corresponds to true, however even in such exceptions, it is a good practice to document the valid values and their meaning to avoid misuse.
Details: An attribute name suggests multiple instances, but its type suggests a single one. One such example is the attribute named statistics of type Boolean. To understand the purpose of the attribute one should follow the uses of the attribute. Such inconsistencies should be documented to avoid additional comprehension effort.
Inconsistency between: attribute name (suggests a collection of objects) and declared type (a type that is not a collection and it is not clear from the documentation what is the purpose of the attribute).
Details: The name of an attribute is in contradiction with its type as they contain antonyms. One such example is the attribute named start of type MAssociationEnd. The use of antonyms can induce wrong assumptions.
Inconsistency between: attribute name and type – they contain terms that have opposite meanings, i.e., antonyms.
Details: The documentation of the entity is in contradiction with its declaration (e.g., name, type). One such example is the attribute named INCLUDE_NAME_DEFAULT whose comment documents an “exclude pattern”. Whether the pattern is included or excluded is therefore unclear when just reading the comment and the attribute name.
Inconsistency between: attribute signature (e.g., name, type) and documentation – they contain terms that have opposite meanings, i.e., antonyms.