==== Meanings of '''public abstract''' ====

==== Meanings of '''public abstract''' ====

Methods marked as '''public abstract''' enforce every subclass to provide their implementation. There is no escape from this and as such this is the primary meaning of this pair of modifiers.

Methods marked as '''public abstract''' enforce every subclass to provide their implementation. There is no escape from this and as such this is the primary meaning of this pair of modifiers. Yet, the method is also '''public''' and as such it can be called by any user of the [[API]]. As such there is a second meaning of the method and needless to say that the [[clarity]] suffers.

 

Yet, the method is also '''public''' and as such it can be called by any user of the [[API]]. So there is second meaning of the method and needless to say that the [[clarity]] suffers.

Although not as bad as '''public''', still there shall be no place for double meaning '''public abstract''' methods in an [[API]], especially on objects that that every user of the [[API]] can get a reference to.

Although not as bad as '''public''', still there shall be no place for double meaning '''public abstract''' methods in an [[API]], especially on objects that that every user of the [[API]] can get a reference to.

Obviously the primary meaning is to allow anyone to call ''public'' method. However there is secondary, yet quite important additional interpretation: one can also re-implement the method in a subclass.

Obviously the primary meaning is to allow anyone to call ''public'' method. However there is secondary, yet quite important additional interpretation: one can also re-implement the method in a subclass.

How dangerous this double meaning can be has been demonstrated in the ''Arithmetica'' example. What troubles such missing [[clarity]] can result in has been described in [[AlternativeBehaviour]]s page. However better than knowing how to cure the problem, is to avoid it: eliminate '''public''' (without no additional modifier) methods from your [[API]]!

How dangerous this double meaning can be has been demonstrated in the ''Arithmetica'' example. What troubles such missing [[clarity]] can result in has been described in [[AlternativeBehaviour]]s page. However better than knowing how to cure the problem, is to avoid it: eliminate '''public''' (without any additional modifier) methods from your [[API]]!

==== Meanings of '''protected''' ====

==== Meanings of '''protected''' ====

or I can share only with my children. This sounds logical and from the point of security it even may be. Yet in combination with '''abstract''' and '''final''' (or '''virtual''' in other languages than [[Java]]) this can cause a complete nightmare when used [[Cluelessness|cluelessly]] during [[API]] design.

or I can share only with my children. This sounds logical and from the point of security it even may be. Yet in combination with '''abstract''' and '''final''' (or '''virtual''' in other languages than [[Java]]) this can cause a complete nightmare when used [[Cluelessness|cluelessly]] during [[API]] design.

[[Clarity]] is important. The easiest way to hurt [[clarity]] is to give one thing multiple meanings. Nobody can then know if someone's understanding of ''the thing'' is correct, full and the same as understanding of somebody else. In a fuzzy environment like this the author and user of an [[API]] cannot really clearly communicate and understand each others intentions.

[[Clarity]] is important. The easiest way to hurt [[clarity]] is to give one thing multiple meanings. Nobody can then know if someone's understanding of ''the thing'' is correct, full and the same as understanding of somebody else. In a fuzzy environment like this the author and user of an [[API]] cannot reliably communicate and understand each others intentions.

==== Meanings of '''public''' ====

==== Meanings of '''public''' ====

==== Meaning of '''protected abstract''' ====

==== Meaning of '''protected abstract''' ====

Abstract methods need to be implemented and that is also the primary meaning of '''protected abstract''' methods. Moreover, being '''protected''' they clearly indicate to all [[API]] users that external (not subclasses) [[API]] users just do not need to care. On the other hand the modifiers shout to all subclasses: ''Implement me!''

Abstract methods need to be implemented and that is also the primary meaning of '''protected abstract''' methods. Moreover, being '''protected''' they clearly indicate to all [[API]] users that external (not subclasses) [[API]] users just do not need to care. This pair of modifiers shouts to all subclasses: ''Implement me!''

=== Eliminating Fuzzy Modifiers ===

=== Eliminating Fuzzy Modifiers ===

Methods marked with '''protected final''' combination cannot be overridden in subclasses. They can be only called. Because of being '''protected''' and not '''public''' they are targeted just for limited set of [[API]] users - only subclasses can call them.

Methods marked with '''protected final''' combination cannot be overridden in subclasses. They can be only called. Because of being '''protected''' and not '''public''' they are targeted just for limited set of [[API]] users - only subclasses can call them.

This can be useful when one provides support classes (like java.util.AbstractList, etc.) which does a bunch of basic functionality. Subclasses then only slightly extend or tune what is premade. Then subclasses can initiate a change in the base superclass by calling '''protected final''' methods.

This can be useful when one provides support classes (like {{JDK|java/util|AbstractList}}, etc.) which does a bunch of basic functionality. Subclasses then only slightly extend or tune what is premade. Then subclasses can initiate a change in the base superclass by calling '''protected final''' methods.

Again the message associated with these modifiers is clear and is just a single one: ''My children, call me!''

Again the message associated with these modifiers is clear and is just a single one: ''My children, call me!''

and implemented?

and implemented?

It can be both. Again, this can be seen as example of power of ''object oriented languages'', but I can guarantee that users of your [[API]] will find such missing [[clarity]] confusing. What is this method good for? I am supposed to use it to communicate with the super class or will super class call it when it finds the need to call it?

It can be both. Again, this can be seen as example of power of ''object oriented languages'', but I can guarantee that users of your [[API]] will find such missing [[clarity]] confusing. What is this method good for? Am I supposed to use it to communicate with the super class or will super class call it when it finds the need to call it?

Nobody can easily tell the meaning of '''protected''' method in an [[API]] class. It is too fuzzy and in the name of [[Clarity]] it deserves to be avoided.

Nobody can easily tell the meaning of '''protected''' method in an [[API]] class. It is too fuzzy and in the name of [[Clarity]] it deserves to be avoided.

or I can share only with my children. This sounds logical and from the point of security it even may be. Yet in combination with '''abstract''' and '''final''' (or '''virtual''' in other languages than [[Java]]) this can cause a complete nightmare when used [[Cluelessness|cluelessly]] during [[API]] design.

or I can share only with my children. This sounds logical and from the point of security it even may be. Yet in combination with '''abstract''' and '''final''' (or '''virtual''' in other languages than [[Java]]) this can cause a complete nightmare when used [[Cluelessness|cluelessly]] during [[API]] design.

[[Clarity]] is important. The easiest way to hurt [[clarity]] is to give one thing multiple meanings. Nobody can then know if someone's understanding of ''the thing'' is correct, full and the same as understanding someone else. In a fuzzy environment like this the author and user of an [[API]] cannot really clearly communicate and understand each others intentions.

[[Clarity]] is important. The easiest way to hurt [[clarity]] is to give one thing multiple meanings. Nobody can then know if someone's understanding of ''the thing'' is correct, full and the same as understanding of somebody else. In a fuzzy environment like this the author and user of an [[API]] cannot really clearly communicate and understand each others intentions.

==== Meanings of '''public''' ====

==== Meanings of '''public''' ====

heads then the [[API]] is clear enough.

heads then the [[API]] is clear enough.

Easy, one might thing. However expressing yourself [[Clarity|clearly]] in some

Easy, one might think. However expressing yourself [[Clarity|clearly]] in some

language requires deep understanding of meaning of its words, sentences and

language requires deep understanding of meaning of its words, sentences and

other language constructs. This is true for English as well as [[Java]]. For

other language constructs. This is true for English as well as [[Java]]. For

Obviously the primary meaning is to allow anyone to call ''public'' method. However there is secondary, yet quite important additional interpretation: one can also re-implement the method in a subclass.

Obviously the primary meaning is to allow anyone to call ''public'' method. However there is secondary, yet quite important additional interpretation: one can also re-implement the method in a subclass.

How dangerous this double meaning can be has been demonstrated in the ''Arithmetica'' example. What troubles such missing [[clarity]] can result in has been described in [[AlternativeBehaviour]]s page. However better than knowing how to cure the problem, is to avoid it: eliminate '''public''' (without no additional modifier) methods for your [[API]]!

How dangerous this double meaning can be has been demonstrated in the ''Arithmetica'' example. What troubles such missing [[clarity]] can result in has been described in [[AlternativeBehaviour]]s page. However better than knowing how to cure the problem, is to avoid it: eliminate '''public''' (without no additional modifier) methods from your [[API]]!

==== Meanings of '''protected''' ====

==== Meanings of '''protected''' ====

[[Category:APIDesignPatterns:Clarity]]

[[Category:APIDesignPatterns:Clarity]]