ClarityOfTypes - Revision history

JaroslavTulach at 08:42, 6 March 2018

2018-03-06T08:42:50Z

←Older revision		Revision as of 08:42, 6 March 2018
Line 1:		Line 1:
-	The fuzziness is all around us, including our [[API]]s. The essay [[ClarityOfAccessModifiers]] explains the importance of correct choice of access modifiers. The [[EliminateFuzzyModifiers]] gives a recipe to turn those fuzzy meanings into [[clarity\|clear]] ones. Yet the result is still not ideal. Something is missing.	+	The [[fuzziness]] is all around us, including our [[API]]s. The essay [[ClarityOfAccessModifiers]] explains the importance of correct choice of access modifiers. The [[EliminateFuzzyModifiers]] gives a recipe to turn those fuzzy meanings into [[clarity\|clear]] ones. Yet the result is still not ideal. Something is missing.

	This essay en-lights what it is. More on the topic can be found in [[Cooperating_with_Other_APIs\|Chapter 10]] of [[TheAPIBook]]. Here is alternative online version.		This essay en-lights what it is. More on the topic can be found in [[Cooperating_with_Other_APIs\|Chapter 10]] of [[TheAPIBook]]. Here is alternative online version.

JaroslavTulach: /* Theory */

2013-08-02T07:22:49Z

Theory

←Older revision		Revision as of 07:22, 2 August 2013
Line 26:		Line 26:
	<source lang="java" snippet="sidemeanings.Mixed.Clean.Factory"/>		<source lang="java" snippet="sidemeanings.Mixed.Clean.Factory"/>

-	The originally '''protected abstract''' methods are moved to ''Provider'' interface. Interface methods are '''public''' and this might seem like a contradiction to [[ClarityOfAccessModifiers]]. However, it is not. The instances of ''Provider'' interface are not accessible to [[ClientAPI\|clients]] of the [[API]]. They are hidden and only useful for the ''create'' factory method that turns them into ''NonMixed'' instances. As such they are ''single meaning'' methods with only one message: ''implement me, don't call me!''. Their [[clarity]] is kept.	+	The originally '''protected abstract''' methods are moved to ''Provider'' interface. Interface methods are '''public''' and this might seem like a contradiction to [[ClarityOfAccessModifiers]]. However, it is not. The instances of ''Provider'' interface are not accessible to [[ClientAPI\|clients]] of the [[API]]. They are hidden and only useful for the ''create'' factory method that turns them into ''NonMixed'' instances. As such they are ''single meaning'' methods in an [[ImplementOnlyInterface]] with only one message: ''implement me, don't call me!''. Their [[clarity]] is kept.

	There is also the ''Callback'' class which holds originally '''protected final''' methods. It is a final class, with non-public constructor, so its creation is fully under the control of the ''NonMixed'' [[API]] infrastructure. Clients of the ''NonMixed'' class cannot get access to it - the reference is only available to the ''Provider'' interface via the ''initialize'' method. As such its use is ''protected'', only ''Provider'' interface implementor can call its methods. Moreover the class is final and as such its methods have only single meaning: ''call me, if you are implementing the provider''. Fully [[Clarity\|clear]] again.		There is also the ''Callback'' class which holds originally '''protected final''' methods. It is a final class, with non-public constructor, so its creation is fully under the control of the ''NonMixed'' [[API]] infrastructure. Clients of the ''NonMixed'' class cannot get access to it - the reference is only available to the ''Provider'' interface via the ''initialize'' method. As such its use is ''protected'', only ''Provider'' interface implementor can call its methods. Moreover the class is final and as such its methods have only single meaning: ''call me, if you are implementing the provider''. Fully [[Clarity\|clear]] again.

JaroslavTulach at 07:19, 2 August 2013

2013-08-02T07:19:22Z

←Older revision		Revision as of 07:19, 2 August 2013
Line 3:		Line 3:
	This essay en-lights what it is. More on the topic can be found in [[Cooperating_with_Other_APIs\|Chapter 10]] of [[TheAPIBook]]. Here is alternative online version.		This essay en-lights what it is. More on the topic can be found in [[Cooperating_with_Other_APIs\|Chapter 10]] of [[TheAPIBook]]. Here is alternative online version.

-	The result of [[EliminateFuzzyModifiers\|elimination of public, protected and public abstract]] can be triplication of each fuzzy method. This may not be bad all times, for example [http://java.sun.com/javase/6/docs/api/java/nio/charset/CharsetDecoder.html CharsetDecoder] successfully provides duplicated versions of its methods (one for [[ClientAPI]] users and one for [[ProviderAPI\|providers]] subclassing the class), but on the other hand this is definitely distracting. Here is an example of correct, but complex elimination:	+	The result of [[EliminateFuzzyModifiers\|elimination of public, protected and public abstract]] can be triplication of each fuzzy method. This may not be bad all times, for example [http://java.sun.com/javase/6/docs/api/java/nio/charset/CharsetDecoder.html CharsetDecoder] successfully provides duplicated versions of its methods (one for [[ClientAPI]] users and one for [[ProviderAPI\|providers]] subclassing the class), but on the other hand this is definitely distracting. Here is an example of more correct, but slightly more complex elimination:

	<source lang="java" snippet="design.sidemeanings.arith.sumTwo"/>		<source lang="java" snippet="design.sidemeanings.arith.sumTwo"/>

JaroslavTulach at 07:18, 2 August 2013

2013-08-02T07:18:24Z

←Older revision		Revision as of 07:18, 2 August 2013
Line 1:		Line 1:
	The fuzziness is all around us, including our [[API]]s. The essay [[ClarityOfAccessModifiers]] explains the importance of correct choice of access modifiers. The [[EliminateFuzzyModifiers]] gives a recipe to turn those fuzzy meanings into [[clarity\|clear]] ones. Yet the result is still not ideal. Something is missing.		The fuzziness is all around us, including our [[API]]s. The essay [[ClarityOfAccessModifiers]] explains the importance of correct choice of access modifiers. The [[EliminateFuzzyModifiers]] gives a recipe to turn those fuzzy meanings into [[clarity\|clear]] ones. Yet the result is still not ideal. Something is missing.

-	This essay en-~~light~~ what is it. More on the topic can be found in [[Cooperating_with_Other_APIs\|Chapter 10]] of [[TheAPIBook]]. Here is alternative online version.	+	This essay en-lights what it is. More on the topic can be found in [[Cooperating_with_Other_APIs\|Chapter 10]] of [[TheAPIBook]]. Here is alternative online version.

	The result of [[EliminateFuzzyModifiers\|elimination of public, protected and public abstract]] can be triplication of each fuzzy method. This may not be bad all times, for example [http://java.sun.com/javase/6/docs/api/java/nio/charset/CharsetDecoder.html CharsetDecoder] successfully provides duplicated versions of its methods (one for [[ClientAPI]] users and one for [[ProviderAPI\|providers]] subclassing the class), but on the other hand this is definitely distracting. Here is an example of correct, but complex elimination:		The result of [[EliminateFuzzyModifiers\|elimination of public, protected and public abstract]] can be triplication of each fuzzy method. This may not be bad all times, for example [http://java.sun.com/javase/6/docs/api/java/nio/charset/CharsetDecoder.html CharsetDecoder] successfully provides duplicated versions of its methods (one for [[ClientAPI]] users and one for [[ProviderAPI\|providers]] subclassing the class), but on the other hand this is definitely distracting. Here is an example of correct, but complex elimination:

JaroslavTulach: /* Evolution Aspects */

2010-02-15T15:38:53Z

Evolution Aspects

←Older revision		Revision as of 15:38, 15 February 2010
Line 48:		Line 48:
	It is easy to [[evolution\|evolve]] the ''Callback'' contract as well. It is also '''final''' and as such adding new methods there is OK. And new methods in ''Callback'' class is exactly what the [[ProviderAPI\|providers]] of the ''Provider'' interface may need in future.		It is easy to [[evolution\|evolve]] the ''Callback'' contract as well. It is also '''final''' and as such adding new methods there is OK. And new methods in ''Callback'' class is exactly what the [[ProviderAPI\|providers]] of the ''Provider'' interface may need in future.

-	Also the [[evolution]] of ''Provider'' interface is possible and easy. Adding new methods into subclassable types is of course not [[BackwardCompatibility\|backward compatible]] at all, but one can always create new interfaces like ''ExtraProvider''. Because of [[DelegationAndComposition]] this addition has no effect on [[ClientAPI]] - the ''NonMixed'' class does not need to change at all. The only thing that may need to be added is new [[factory]] method for each new interface. But that is quite well thought [[evolution\|evolution plan]].	+	Also the [[evolution]] of ''Provider'' interface is possible and easy. Adding new methods into subclassable types is of course not [[BackwardCompatibility\|backward compatible]] at all, but one can always create new interfaces like ''ExtraProvider''. Because of [[DelegationAndComposition]] this addition has no effect on [[ClientAPI]] - the ''NonMixed'' class [[API]] does not need to change at all. The only thing that may need to be added is new [[factory]] method for each new interface. But that is quite well thought [[evolution\|evolution plan]].

	<comments/>		<comments/>

JaroslavTulach: /* Evolution Aspects */

2010-02-15T15:37:51Z

Evolution Aspects

←Older revision		Revision as of 15:37, 15 February 2010
Line 53:		Line 53:


-	[[Category:APIDesignPatterns:Clarity]] [[Category:APIDesignPatterns]]	+	[[Category:APIDesignPatterns:Clarity]] [[Category:APIDesignPatterns]] [[Category:APIDesignPatterns:Evolution]]

JaroslavTulach: /* Evolution Aspects */

2009-04-01T16:49:26Z

Evolution Aspects

←Older revision		Revision as of 16:49, 1 April 2009
Line 53:		Line 53:


-	[[Category:APIDesignPatterns:Clarity]] [[Category:APIDesignPatterns~~:Clarity~~]]	+	[[Category:APIDesignPatterns:Clarity]] [[Category:APIDesignPatterns]]

JaroslavTulach: /* Clarity for Clients */

2009-04-01T16:48:09Z

Clarity for Clients

←Older revision		Revision as of 16:48, 1 April 2009
Line 32:		Line 32:
	=== [[Clarity]] for [[ClientAPI\|Clients]] ===		=== [[Clarity]] for [[ClientAPI\|Clients]] ===

-	Clients that hold reference to ''NonMixed'' class see only its '''public''' methods in [[Javadoc]], IDE code completion, etc. They are not distracted by details useful only for providers. The code that [[ClientAPI\|callers]] need to provide is ~~completely the~~ same as in the original ''Mixed'' class - e.g. we achieved [[clarity]] for [[ClientAPI\|callers]] without complicating their code even a bit (see the calls in the example in following section)!	+	Clients that hold reference to ''NonMixed'' class see only its '''public''' methods in [[Javadoc]], IDE code completion, etc. They are not distracted by details useful only for providers. The code that [[ClientAPI\|callers]] need to provide is absolutelly same as the one when using the original ''Mixed'' class - e.g. we achieved [[clarity]] for [[ClientAPI\|callers]] without complicating their code even a bit (see the calls in the example in following section)!

	=== [[Clarity]] for [[ProviderAPI\|Implementors]] ===		=== [[Clarity]] for [[ProviderAPI\|Implementors]] ===

JaroslavTulach at 16:44, 1 April 2009

2009-04-01T16:44:06Z

←Older revision		Revision as of 16:44, 1 April 2009
Line 3:		Line 3:
	This essay en-light what is it. More on the topic can be found in [[Cooperating_with_Other_APIs\|Chapter 10]] of [[TheAPIBook]]. Here is alternative online version.		This essay en-light what is it. More on the topic can be found in [[Cooperating_with_Other_APIs\|Chapter 10]] of [[TheAPIBook]]. Here is alternative online version.

-	The result of [[EliminateFuzzyModifiers\|elimination of public, protected and public abstract]] can be triplication of each fuzzy method. This may not be bad in all times, for example [http://java.sun.com/javase/6/docs/api/java/nio/charset/CharsetDecoder.html CharsetDecoder] successfully provides duplicated versions of its methods (one for [[ClientAPI]] users and one for [[ProviderAPI\|providers]] subclassing the class), but on the other hand this is definitely distracting. Here is an example of correct, but complex elimination:	+	The result of [[EliminateFuzzyModifiers\|elimination of public, protected and public abstract]] can be triplication of each fuzzy method. This may not be bad all times, for example [http://java.sun.com/javase/6/docs/api/java/nio/charset/CharsetDecoder.html CharsetDecoder] successfully provides duplicated versions of its methods (one for [[ClientAPI]] users and one for [[ProviderAPI\|providers]] subclassing the class), but on the other hand this is definitely distracting. Here is an example of correct, but complex elimination:

	<source lang="java" snippet="design.sidemeanings.arith.sumTwo"/>		<source lang="java" snippet="design.sidemeanings.arith.sumTwo"/>

JaroslavTulach at 16:43, 1 April 2009

2009-04-01T16:43:42Z

←Older revision		Revision as of 16:43, 1 April 2009
Line 1:		Line 1:
	The fuzziness is all around us, including our [[API]]s. The essay [[ClarityOfAccessModifiers]] explains the importance of correct choice of access modifiers. The [[EliminateFuzzyModifiers]] gives a recipe to turn those fuzzy meanings into [[clarity\|clear]] ones. Yet the result is still not ideal. Something is missing.		The fuzziness is all around us, including our [[API]]s. The essay [[ClarityOfAccessModifiers]] explains the importance of correct choice of access modifiers. The [[EliminateFuzzyModifiers]] gives a recipe to turn those fuzzy meanings into [[clarity\|clear]] ones. Yet the result is still not ideal. Something is missing.

-	This essay en-light what is it. More on the topic can be found in [[Cooperating_with_Other_APIs\|Chapter 10]] of [[TheAPIBook]]. Here is ~~a shorter~~ version.	+	This essay en-light what is it. More on the topic can be found in [[Cooperating_with_Other_APIs\|Chapter 10]] of [[TheAPIBook]]. Here is alternative online version.

	The result of [[EliminateFuzzyModifiers\|elimination of public, protected and public abstract]] can be triplication of each fuzzy method. This may not be bad in all times, for example [http://java.sun.com/javase/6/docs/api/java/nio/charset/CharsetDecoder.html CharsetDecoder] successfully provides duplicated versions of its methods (one for [[ClientAPI]] users and one for [[ProviderAPI\|providers]] subclassing the class), but on the other hand this is definitely distracting. Here is an example of correct, but complex elimination:		The result of [[EliminateFuzzyModifiers\|elimination of public, protected and public abstract]] can be triplication of each fuzzy method. This may not be bad in all times, for example [http://java.sun.com/javase/6/docs/api/java/nio/charset/CharsetDecoder.html CharsetDecoder] successfully provides duplicated versions of its methods (one for [[ClientAPI]] users and one for [[ProviderAPI\|providers]] subclassing the class), but on the other hand this is definitely distracting. Here is an example of correct, but complex elimination:

←Older revision		Revision as of 07:18, 2 August 2013
Line 1:		Line 1:
	The fuzziness is all around us, including our [[API]]s. The essay [[ClarityOfAccessModifiers]] explains the importance of correct choice of access modifiers. The [[EliminateFuzzyModifiers]] gives a recipe to turn those fuzzy meanings into [[clarity\|clear]] ones. Yet the result is still not ideal. Something is missing.		The fuzziness is all around us, including our [[API]]s. The essay [[ClarityOfAccessModifiers]] explains the importance of correct choice of access modifiers. The [[EliminateFuzzyModifiers]] gives a recipe to turn those fuzzy meanings into [[clarity\|clear]] ones. Yet the result is still not ideal. Something is missing.

-	This essay en-~~light~~ what is it. More on the topic can be found in [[Cooperating_with_Other_APIs\|Chapter 10]] of [[TheAPIBook]]. Here is alternative online version.	+	This essay en-lights what it is. More on the topic can be found in [[Cooperating_with_Other_APIs\|Chapter 10]] of [[TheAPIBook]]. Here is alternative online version.

	The result of [[EliminateFuzzyModifiers\|elimination of public, protected and public abstract]] can be triplication of each fuzzy method. This may not be bad all times, for example [http://java.sun.com/javase/6/docs/api/java/nio/charset/CharsetDecoder.html CharsetDecoder] successfully provides duplicated versions of its methods (one for [[ClientAPI]] users and one for [[ProviderAPI\|providers]] subclassing the class), but on the other hand this is definitely distracting. Here is an example of correct, but complex elimination:		The result of [[EliminateFuzzyModifiers\|elimination of public, protected and public abstract]] can be triplication of each fuzzy method. This may not be bad all times, for example [http://java.sun.com/javase/6/docs/api/java/nio/charset/CharsetDecoder.html CharsetDecoder] successfully provides duplicated versions of its methods (one for [[ClientAPI]] users and one for [[ProviderAPI\|providers]] subclassing the class), but on the other hand this is definitely distracting. Here is an example of correct, but complex elimination:

←Older revision		Revision as of 16:48, 1 April 2009
Line 32:		Line 32:
	=== [[Clarity]] for [[ClientAPI\|Clients]] ===		=== [[Clarity]] for [[ClientAPI\|Clients]] ===

-	Clients that hold reference to ''NonMixed'' class see only its '''public''' methods in [[Javadoc]], IDE code completion, etc. They are not distracted by details useful only for providers. The code that [[ClientAPI\|callers]] need to provide is ~~completely the~~ same as in the original ''Mixed'' class - e.g. we achieved [[clarity]] for [[ClientAPI\|callers]] without complicating their code even a bit (see the calls in the example in following section)!	+	Clients that hold reference to ''NonMixed'' class see only its '''public''' methods in [[Javadoc]], IDE code completion, etc. They are not distracted by details useful only for providers. The code that [[ClientAPI\|callers]] need to provide is absolutelly same as the one when using the original ''Mixed'' class - e.g. we achieved [[clarity]] for [[ClientAPI\|callers]] without complicating their code even a bit (see the calls in the example in following section)!

	=== [[Clarity]] for [[ProviderAPI\|Implementors]] ===		=== [[Clarity]] for [[ProviderAPI\|Implementors]] ===

←Older revision		Revision as of 16:43, 1 April 2009
Line 1:		Line 1:
	The fuzziness is all around us, including our [[API]]s. The essay [[ClarityOfAccessModifiers]] explains the importance of correct choice of access modifiers. The [[EliminateFuzzyModifiers]] gives a recipe to turn those fuzzy meanings into [[clarity\|clear]] ones. Yet the result is still not ideal. Something is missing.		The fuzziness is all around us, including our [[API]]s. The essay [[ClarityOfAccessModifiers]] explains the importance of correct choice of access modifiers. The [[EliminateFuzzyModifiers]] gives a recipe to turn those fuzzy meanings into [[clarity\|clear]] ones. Yet the result is still not ideal. Something is missing.

-	This essay en-light what is it. More on the topic can be found in [[Cooperating_with_Other_APIs\|Chapter 10]] of [[TheAPIBook]]. Here is ~~a shorter~~ version.	+	This essay en-light what is it. More on the topic can be found in [[Cooperating_with_Other_APIs\|Chapter 10]] of [[TheAPIBook]]. Here is alternative online version.

	The result of [[EliminateFuzzyModifiers\|elimination of public, protected and public abstract]] can be triplication of each fuzzy method. This may not be bad in all times, for example [http://java.sun.com/javase/6/docs/api/java/nio/charset/CharsetDecoder.html CharsetDecoder] successfully provides duplicated versions of its methods (one for [[ClientAPI]] users and one for [[ProviderAPI\|providers]] subclassing the class), but on the other hand this is definitely distracting. Here is an example of correct, but complex elimination:		The result of [[EliminateFuzzyModifiers\|elimination of public, protected and public abstract]] can be triplication of each fuzzy method. This may not be bad in all times, for example [http://java.sun.com/javase/6/docs/api/java/nio/charset/CharsetDecoder.html CharsetDecoder] successfully provides duplicated versions of its methods (one for [[ClientAPI]] users and one for [[ProviderAPI\|providers]] subclassing the class), but on the other hand this is definitely distracting. Here is an example of correct, but complex elimination: