EliminateFuzzyModifiers - Revision history

JaroslavTulach: /* Different API */

2013-08-02T07:16:26Z

Different API

←Older revision		Revision as of 07:16, 2 August 2013
Line 85:		Line 85:
	=== 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''.

JaroslavTulach: /* Protected */

2013-08-02T07:12:05Z

Protected

←Older revision		Revision as of 07:12, 2 August 2013
Line 27:		Line 27:
	=== 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"/>

Apidesign: /* Pre/Post Conditions */

2012-09-11T07:55:26Z

Pre/Post Conditions

←Older revision		Revision as of 07:55, 11 September 2012
Line 111:		Line 111:
	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]]

Apidesign: /* Pre/Post Conditions */

2012-09-11T07:55:06Z

Pre/Post Conditions

←Older revision		Revision as of 07:55, 11 September 2012
Line 112:		Line 112:

	TBD: Allows pre/post conditions. E.g. enforcing consistency of an API		TBD: Allows pre/post conditions. E.g. enforcing consistency of an API
-
-	~~<comments/>~~

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

Cordeo: Typo correction: once => one

2010-04-14T10:24:17Z

Typo correction: once => one

←Older revision		Revision as of 10:24, 14 April 2010
Line 35:		Line 35:
	<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"/>

JaroslavTulach: /* Pre/Post Conditions */

2009-03-27T21:05:14Z

Pre/Post Conditions

←Older revision		Revision as of 21:05, 27 March 2009
Line 109:		Line 109:
	=== 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

JaroslavTulach: /* Support for Factorial like Use Case */

2009-03-27T21:04:10Z

Support for Factorial like Use Case

←Older revision		Revision as of 21:04, 27 March 2009
Line 103:		Line 103:
	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]].

-	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.	+	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]].

JaroslavTulach: /* Support for Factorial like Use Case */

2009-03-27T21:03:51Z

Support for Factorial like Use Case

←Older revision		Revision as of 21:03, 27 March 2009
Line 103:		Line 103:
	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]].

JaroslavTulach: /* Support for Factorial like Use Case */

2009-03-27T21:03:18Z

Support for Factorial like Use Case

←Older revision		Revision as of 21:03, 27 March 2009
Line 101:		Line 101:
	=== 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.

JaroslavTulach: /* Different API */

2009-03-27T21:01:31Z

Different API

←Older revision		Revision as of 21:01, 27 March 2009
Line 87:		Line 87:
	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: