=== Different [[API]] ===

=== Different [[API]] ===

The important thing is that the choice of modifiers can turn the [[API]] into something completely else. Boths [[API]]s can be useful in certain situations, but one shall be aware that they are completely different. It is not necessary to [[EliminateFuzzyModifiers]] all the time, but remember to do the mental exercise to try it in your mind at least. Only then you'll see what kind of [[API]] your are in fact giving to your users.

The important thing is that the choice of modifiers can turn the [[API]] into something completely else. Boths [[API]]s can be useful in certain situations, but one shall be aware that they are completely different. It is not necessary to [[EliminateFuzzyModifiers]] all the time, but remember to perform such mental exercise in your mind at least. Only then you'll see what kind of [[API]] you are in fact giving to your users.

In the particular ''Arithmetica'' example the intention very likely is (especially in the light of future optimization suggested in [[AlternativeBehaviour]]) to support just summing numbers. Computing ''factorial'' is a misuse, not a use case. In such case, one wants to call the ''defaultSumAll'' and ''defaultSumTwo''.

In the particular ''Arithmetica'' example the intention very likely is (especially in the light of future optimization suggested in [[AlternativeBehaviour]]) to support just summing numbers. Computing ''factorial'' is a misuse, not a use case. In such case, one wants to call the ''defaultSumAll'' and ''defaultSumTwo''.

=== Protected ===

=== Protected ===

'''protected''' methods are also [[ClarityOfAccessModifiers|said to have double meaning]]]. They can be overriden, plus they can carry some implementation for subclasses to call just like in this example:

'''protected''' methods are also [[ClarityOfAccessModifiers|said to have double meaning]]. They can be overriden, plus they can carry some implementation for subclasses to call just like in this example:

<source lang="java" snippet="sidemeanings.Protected.Dirty"/>

<source lang="java" snippet="sidemeanings.Protected.Dirty"/>

Careful readers might have realized that the split to '''public''' '''final''' method and '''protected''' '''abstract''' in fact allows the [[API]] to enforce pre/post conditions inside of the '''final''' method. This is very good for [[clarity]] and consistency too. But again more about that in [[Cooperating_with_Other_APIs|Chapter 10]] or later, if there is some interest...

Careful readers might have realized that the split to '''public''' '''final''' method and '''protected''' '''abstract''' in fact allows the [[API]] to enforce pre/post conditions inside of the '''final''' method. This is very good for [[clarity]] and consistency too. But again more about that in [[Cooperating_with_Other_APIs|Chapter 10]] or later, if there is some interest...

TBD: Allows pre/post conditions. E.g. enforcing consistency of an API

[[TBD]]: Allows pre/post conditions. E.g. enforcing consistency of an API

[[Category:APIDesignPatterns]] [[Category:APIDesignPatterns:Clarity]] [[Category:APIDesignPatterns:Consistency]]

[[Category:APIDesignPatterns]] [[Category:APIDesignPatterns:Clarity]] [[Category:APIDesignPatterns:Consistency]]

TBD: Allows pre/post conditions. E.g. enforcing consistency of an API

TBD: Allows pre/post conditions. E.g. enforcing consistency of an API

[[Category:APIDesignPatterns]] [[Category:APIDesignPatterns:Clarity]] [[Category:APIDesignPatterns:Consistency]]

[[Category:APIDesignPatterns]] [[Category:APIDesignPatterns:Clarity]] [[Category:APIDesignPatterns:Consistency]]

<source lang="java" snippet="sidemeanings.Protected.Clean"/>

<source lang="java" snippet="sidemeanings.Protected.Clean"/>

The expressive power of such [[API]] remains unchanged. Once can still rewrite code that is using the old version:

The expressive power of such [[API]] remains unchanged. One can still rewrite code that is using the old version:

<source lang="java" snippet="sidemeanings.Protected.Dirty.test"/>

<source lang="java" snippet="sidemeanings.Protected.Dirty.test"/>

=== Pre/Post Conditions ===

=== Pre/Post Conditions ===

Careful readers might have realized that the split to '''public''' '''final''' method and '''protected''' '''abstract''' in fact allow the [[API]] to enforce pre/post conditions inside of the '''final''' method. This is very good for [[clarity]] and consistency too. But again more about that in [[Cooperating_with_Other_APIs|Chapter 10]] or later, if there is some interest...

Careful readers might have realized that the split to '''public''' '''final''' method and '''protected''' '''abstract''' in fact allows the [[API]] to enforce pre/post conditions inside of the '''final''' method. This is very good for [[clarity]] and consistency too. But again more about that in [[Cooperating_with_Other_APIs|Chapter 10]] or later, if there is some interest...

TBD: Allows pre/post conditions. E.g. enforcing consistency of an API

TBD: Allows pre/post conditions. E.g. enforcing consistency of an API

If, on the other hand, we decide to support subclassing, we'll be left with up-to triple methods for the ''same thing'' in one class. As you can imagine this may not look good in [[Javadoc]]. Why do users who just call into the class need to be bothered with information about methods only for subclasses? This is not real [[cluelessness]].

If, on the other hand, we decide to support subclassing, we'll be left with up-to triple methods for the ''same thing'' in one class. As you can imagine this may not look good in [[Javadoc]]. Why do users who just call into the class need to be bothered with information about methods only for subclasses? This is not real [[cluelessness]].

It need not be that bad, for example the [http://java.sun.com/javase/6/docs/api/java/nio/charset/CharsetEncoder.html java.nio.charset.CharsetEncoder] is using style with '''public''' XYZ methods and pair '''protected''' implXYZ ones. But when we seek [[clarity]], we shall not stop. We shall seek for better alternative.

On the other hand, the situation is not necessarily that bad, for example the [http://java.sun.com/javase/6/docs/api/java/nio/charset/CharsetEncoder.html java.nio.charset.CharsetEncoder] is using style with '''public''' XYZ methods and pair '''protected''' implXYZ ones. But when we seek [[clarity]], we shall not stop. We shall seek for better alternative.

Let's think about [[ClarityOfTypes]] - but let's leave this for next time. If there is an interest, I'll reveal more. Meanwhile you may want to find the answer in [[Cooperating_with_Other_APIs|Chapter 10]], Cooperating with Other APIs of [[TheAPIBook]].

Let's think about [[ClarityOfTypes]] - but let's leave this for next time. If there is an interest, I'll reveal more. Meanwhile you may want to find the answer in [[Cooperating_with_Other_APIs|Chapter 10]], Cooperating with Other APIs of [[TheAPIBook]].

=== Support for Factorial like Use Case ===

=== Support for Factorial like Use Case ===

If, on the other hand, we decide to support subclassing, we'll be left with up-to triple methods for the ''same thing'' in one class. As you can imagine this may not look good in [[Javadoc]]. Why do users who just call into the class need to be bothered with information about methods only for subclasses?

If, on the other hand, we decide to support subclassing, we'll be left with up-to triple methods for the ''same thing'' in one class. As you can imagine this may not look good in [[Javadoc]]. Why do users who just call into the class need to be bothered with information about methods only for subclasses? This is not real [[cluelessness]].

It need not be that bad, for example the [http://java.sun.com/javase/6/docs/api/java/nio/charset/CharsetEncoder.html java.nio.charset.CharsetEncoder] is using style with '''public''' XYZ methods and pair '''protected''' implXYZ ones. But when we seek [[clarity]], we shall not stop. We shall seek for better alternative.

It need not be that bad, for example the [http://java.sun.com/javase/6/docs/api/java/nio/charset/CharsetEncoder.html java.nio.charset.CharsetEncoder] is using style with '''public''' XYZ methods and pair '''protected''' implXYZ ones. But when we seek [[clarity]], we shall not stop. We shall seek for better alternative.

The important thing is that the choice of modifiers can turn the [[API]] into something completely else. Boths [[API]]s can be useful in certain situations, but one shall be aware that they are completely different. It is not necessary to [[EliminateFuzzyModifiers]] all the time, but remember to do the mental exercise to try it in your mind at least. Only then you'll see what kind of [[API]] your are in fact giving to your users.

The important thing is that the choice of modifiers can turn the [[API]] into something completely else. Boths [[API]]s can be useful in certain situations, but one shall be aware that they are completely different. It is not necessary to [[EliminateFuzzyModifiers]] all the time, but remember to do the mental exercise to try it in your mind at least. Only then you'll see what kind of [[API]] your are in fact giving to your users.

In the particular ''Arithmetica'' example the intention very likely is (especially in the light of optimizations suggested in [[AlternativeBehaviour]]) to support just summing numbers. Computing ''factorial'' is a misuse, not a use case. In such case, one wants to call the ''defaultSumAll'' and ''defaultSumTwo''.

In the particular ''Arithmetica'' example the intention very likely is (especially in the light of future optimization suggested in [[AlternativeBehaviour]]) to support just summing numbers. Computing ''factorial'' is a misuse, not a use case. In such case, one wants to call the ''defaultSumAll'' and ''defaultSumTwo''.

Moreover the subclassing is not a use case either. As such it makes sense to eliminate all the '''protected''' methods and restrict the [[API]] to just:

Moreover the subclassing is not a use case either. As such it makes sense to eliminate all the '''protected''' methods and restrict the [[API]] to just: