Conceptual surface - Revision history

JaroslavTulach: /* API vs. Implementation */

2025-02-15T04:18:51Z

API vs. Implementation

←Older revision		Revision as of 04:18, 15 February 2025
Line 4:		Line 4:

	The primary rule comes from [[Chapter 6]] of [[TheAPIBook]] called [[Code Against Interfaces, Not Implementations]]: make sure to '''distinguish''' between [[API]] and '''implementation'''! [[API]] is supposed to act as a ''facade'' hiding the gory implementation details. The fact that something is implemented by ten different implementation classes doesn't mean all of them have to be exposed to users of the [[API]]!		The primary rule comes from [[Chapter 6]] of [[TheAPIBook]] called [[Code Against Interfaces, Not Implementations]]: make sure to '''distinguish''' between [[API]] and '''implementation'''! [[API]] is supposed to act as a ''facade'' hiding the gory implementation details. The fact that something is implemented by ten different implementation classes doesn't mean all of them have to be exposed to users of the [[API]]!
		+
		+	<!-- show example from https://vmmeetup.github.io/2015/
		+
		+	An API for a multi-threaded, multi-language, multi-tenant, multi-node VM
		+	Jaroslav Tulach, Oracle Labs
		+
		+	Comparing the Interop API before and after cleanup
		+
		+	-->

	Don't mix [[API]] and implementation in one package or (if you do) make implementation '''private''' so it is not visible in the [[javadoc]]. When you split [[API]] and implementation into separate packages, consider using [[FriendPackages]] accessor so the [[API]] package has a '''priviledged''' access to the implementation when it needs it. Discourage people from using implementation by making it package private, or in case of [[Modular_Java_SE\|Java Modular system]] by ''exporting only API'' package outside of your module.		Don't mix [[API]] and implementation in one package or (if you do) make implementation '''private''' so it is not visible in the [[javadoc]]. When you split [[API]] and implementation into separate packages, consider using [[FriendPackages]] accessor so the [[API]] package has a '''priviledged''' access to the implementation when it needs it. Discourage people from using implementation by making it package private, or in case of [[Modular_Java_SE\|Java Modular system]] by ''exporting only API'' package outside of your module.

JaroslavTulach: /* References */

2025-02-15T04:08:46Z

References

←Older revision		Revision as of 04:08, 15 February 2025
Line 13:		Line 13:
	=== References ===		=== References ===

-	~~Before~~ of [[Leaky abstractions]] and [[LeakingCulturalContext]].	+	Beware of [[Leaky abstractions]] and [[LeakingCulturalContext]].

	[[Category:APIDesignPatterns:Clarity]] [[Category:APIDesignPatterns:Meta]]		[[Category:APIDesignPatterns:Clarity]] [[Category:APIDesignPatterns:Meta]]

JaroslavTulach: /* API vs. Implementation */

2025-02-15T04:07:06Z

API vs. Implementation

←Older revision		Revision as of 04:07, 15 February 2025
Line 3:		Line 3:
	=== API vs. Implementation ===		=== API vs. Implementation ===

-	The primary rule comes from [[Chapter 6]] of [[TheAPIBook]] called [[Code Against Interfaces, Not Implementations]]: make sure to '''distinguish''' between [[API]] and '''implementation'''! [[API]] is supposed to act as a ''facade'' hiding the gory implementation details. The fact that something is implemented by ten different implementation classes doesn't mean all of them ~~have to be~~ have to be exposed to users of the [[API]]!	+	The primary rule comes from [[Chapter 6]] of [[TheAPIBook]] called [[Code Against Interfaces, Not Implementations]]: make sure to '''distinguish''' between [[API]] and '''implementation'''! [[API]] is supposed to act as a ''facade'' hiding the gory implementation details. The fact that something is implemented by ten different implementation classes doesn't mean all of them have to be exposed to users of the [[API]]!

	Don't mix [[API]] and implementation in one package or (if you do) make implementation '''private''' so it is not visible in the [[javadoc]]. When you split [[API]] and implementation into separate packages, consider using [[FriendPackages]] accessor so the [[API]] package has a '''priviledged''' access to the implementation when it needs it. Discourage people from using implementation by making it package private, or in case of [[Modular_Java_SE\|Java Modular system]] by ''exporting only API'' package outside of your module.		Don't mix [[API]] and implementation in one package or (if you do) make implementation '''private''' so it is not visible in the [[javadoc]]. When you split [[API]] and implementation into separate packages, consider using [[FriendPackages]] accessor so the [[API]] package has a '''priviledged''' access to the implementation when it needs it. Discourage people from using implementation by making it package private, or in case of [[Modular_Java_SE\|Java Modular system]] by ''exporting only API'' package outside of your module.

JaroslavTulach at 04:06, 15 February 2025

2025-02-15T04:06:07Z

←Older revision		Revision as of 04:06, 15 February 2025
Line 1:		Line 1:
	The term [[conceptual surface]] has been coined by [[Tim Boudreau]] during our talks about [[API Design]]. It describes the amount of concepts one needs to understand when dealing with an [[API]]. [[Conceptual surface]] metric is a very useful way to measure '''complexity''' of an [[API]].		The term [[conceptual surface]] has been coined by [[Tim Boudreau]] during our talks about [[API Design]]. It describes the amount of concepts one needs to understand when dealing with an [[API]]. [[Conceptual surface]] metric is a very useful way to measure '''complexity''' of an [[API]].

-	~~One~~ common advice when it comes to separating [[APIvsSPI]] is to make sure the classes in the [[ClientAPI]] part (e.g. the [[conceptual surface]] of the [[API]]) doesn't reference the service provider part ([[SPI]]). This advice optimizes for the common case where the number of people making calls into the [[API]] (e.g. using the [[ClientAPI]] part) is an order of magnitude bigger than those providing implementation of services (e.g. [[ProviderAPI]]). Also the service provider part is often more complicated and could scary the [[cluelessness]] out of newcomers.	+	=== API vs. Implementation ===
		+
		+	The primary rule comes from [[Chapter 6]] of [[TheAPIBook]] called [[Code Against Interfaces, Not Implementations]]: make sure to '''distinguish''' between [[API]] and '''implementation'''! [[API]] is supposed to act as a ''facade'' hiding the gory implementation details. The fact that something is implemented by ten different implementation classes doesn't mean all of them have to be have to be exposed to users of the [[API]]!
		+
		+	Don't mix [[API]] and implementation in one package or (if you do) make implementation '''private''' so it is not visible in the [[javadoc]]. When you split [[API]] and implementation into separate packages, consider using [[FriendPackages]] accessor so the [[API]] package has a '''priviledged''' access to the implementation when it needs it. Discourage people from using implementation by making it package private, or in case of [[Modular_Java_SE\|Java Modular system]] by ''exporting only API'' package outside of your module.
		+
		+	=== [[APIvsSPI]] ===
		+
		+	Another common advice when it comes to separating [[APIvsSPI]] is to make sure the classes in the [[ClientAPI]] part (e.g. the [[conceptual surface]] of the [[API]]) doesn't reference the service provider part ([[SPI]]). This advice optimizes for the common case where the number of people making calls into the [[API]] (e.g. using the [[ClientAPI]] part) is an order of magnitude bigger than those providing implementation of services (e.g. [[ProviderAPI]]). Also the service provider part is often more complicated and could scary the [[cluelessness]] out of newcomers.
		+
		+	=== References ===
		+
		+	Before of [[Leaky abstractions]] and [[LeakingCulturalContext]].

	[[Category:APIDesignPatterns:Clarity]] [[Category:APIDesignPatterns:Meta]]		[[Category:APIDesignPatterns:Clarity]] [[Category:APIDesignPatterns:Meta]]

JaroslavTulach at 08:41, 1 February 2018

2018-02-01T08:41:57Z

←Older revision		Revision as of 08:41, 1 February 2018
Line 1:		Line 1:
-	The term [[conceptual surface]] has been coined by [[Tim Boudreau]] during our talks about [[API Design]]. It describes the amount of concepts one needs to understand when dealing with an [[API]]. [[Conceptual surface]] metric is a very way to measure '''complexity''' of an [[API]].	+	The term [[conceptual surface]] has been coined by [[Tim Boudreau]] during our talks about [[API Design]]. It describes the amount of concepts one needs to understand when dealing with an [[API]]. [[Conceptual surface]] metric is a very useful way to measure '''complexity''' of an [[API]].

	One common advice when it comes to separating [[APIvsSPI]] is to make sure the classes in the [[ClientAPI]] part (e.g. the [[conceptual surface]] of the [[API]]) doesn't reference the service provider part ([[SPI]]). This advice optimizes for the common case where the number of people making calls into the [[API]] (e.g. using the [[ClientAPI]] part) is an order of magnitude bigger than those providing implementation of services (e.g. [[ProviderAPI]]). Also the service provider part is often more complicated and could scary the [[cluelessness]] out of newcomers.		One common advice when it comes to separating [[APIvsSPI]] is to make sure the classes in the [[ClientAPI]] part (e.g. the [[conceptual surface]] of the [[API]]) doesn't reference the service provider part ([[SPI]]). This advice optimizes for the common case where the number of people making calls into the [[API]] (e.g. using the [[ClientAPI]] part) is an order of magnitude bigger than those providing implementation of services (e.g. [[ProviderAPI]]). Also the service provider part is often more complicated and could scary the [[cluelessness]] out of newcomers.

	[[Category:APIDesignPatterns:Clarity]] [[Category:APIDesignPatterns:Meta]]		[[Category:APIDesignPatterns:Clarity]] [[Category:APIDesignPatterns:Meta]]

JaroslavTulach at 08:07, 1 February 2018

2018-02-01T08:07:10Z

←Older revision		Revision as of 08:07, 1 February 2018
Line 1:		Line 1:
	The term [[conceptual surface]] has been coined by [[Tim Boudreau]] during our talks about [[API Design]]. It describes the amount of concepts one needs to understand when dealing with an [[API]]. [[Conceptual surface]] metric is a very way to measure '''complexity''' of an [[API]].		The term [[conceptual surface]] has been coined by [[Tim Boudreau]] during our talks about [[API Design]]. It describes the amount of concepts one needs to understand when dealing with an [[API]]. [[Conceptual surface]] metric is a very way to measure '''complexity''' of an [[API]].

-	One common advice when it comes to separating [[APIvsSPI]] is to make sure the classes in the [[ClientAPI]] part (e.g. the [[conceptual surface]] of the [[API]]) doesn't reference the service provider part ([[SPI]]). This advice optimizes for the common case where the number of people making calls into the [[API]] (e.g. using the [[ClientAPI]] part) is an order of magnitude bigger than those providing implementation of services (e.g. [[~~ProviderSPI~~]]). Also the service provider part is often more complicated and could scary the [[cluelessness]] out of newcomers.	+	One common advice when it comes to separating [[APIvsSPI]] is to make sure the classes in the [[ClientAPI]] part (e.g. the [[conceptual surface]] of the [[API]]) doesn't reference the service provider part ([[SPI]]). This advice optimizes for the common case where the number of people making calls into the [[API]] (e.g. using the [[ClientAPI]] part) is an order of magnitude bigger than those providing implementation of services (e.g. [[ProviderAPI]]). Also the service provider part is often more complicated and could scary the [[cluelessness]] out of newcomers.

	[[Category:APIDesignPatterns:Clarity]] [[Category:APIDesignPatterns:Meta]]		[[Category:APIDesignPatterns:Clarity]] [[Category:APIDesignPatterns:Meta]]

JaroslavTulach at 08:06, 1 February 2018

2018-02-01T08:06:56Z

←Older revision		Revision as of 08:06, 1 February 2018
Line 1:		Line 1:
-	The term [[conceptual surface]] has been coined by [[Tim Boudreau]] during our talks about [[API Design]]. It describes the amount of concepts one needs to understand when dealing with an [[API]].	+	The term [[conceptual surface]] has been coined by [[Tim Boudreau]] during our talks about [[API Design]]. It describes the amount of concepts one needs to understand when dealing with an [[API]]. [[Conceptual surface]] metric is a very way to measure '''complexity''' of an [[API]].

	One common advice when it comes to separating [[APIvsSPI]] is to make sure the classes in the [[ClientAPI]] part (e.g. the [[conceptual surface]] of the [[API]]) doesn't reference the service provider part ([[SPI]]). This advice optimizes for the common case where the number of people making calls into the [[API]] (e.g. using the [[ClientAPI]] part) is an order of magnitude bigger than those providing implementation of services (e.g. [[ProviderSPI]]). Also the service provider part is often more complicated and could scary the [[cluelessness]] out of newcomers.		One common advice when it comes to separating [[APIvsSPI]] is to make sure the classes in the [[ClientAPI]] part (e.g. the [[conceptual surface]] of the [[API]]) doesn't reference the service provider part ([[SPI]]). This advice optimizes for the common case where the number of people making calls into the [[API]] (e.g. using the [[ClientAPI]] part) is an order of magnitude bigger than those providing implementation of services (e.g. [[ProviderSPI]]). Also the service provider part is often more complicated and could scary the [[cluelessness]] out of newcomers.

	[[Category:APIDesignPatterns:Clarity]] [[Category:APIDesignPatterns:Meta]]		[[Category:APIDesignPatterns:Clarity]] [[Category:APIDesignPatterns:Meta]]

JaroslavTulach: New page: The term conceptual surface has been coined by Tim Boudreau during our talks about API Design. It describes the amount of concepts one needs to understand when dealing with an ...

2018-02-01T08:05:08Z

New page: The term conceptual surface has been coined by Tim Boudreau during our talks about API Design. It describes the amount of concepts one needs to understand when dealing with an ...

New page

The term [[conceptual surface]] has been coined by [[Tim Boudreau]] during our talks about [[API Design]]. It describes the amount of concepts one needs to understand when dealing with an [[API]].

One common advice when it comes to separating [[APIvsSPI]] is to make sure the classes in the [[ClientAPI]] part (e.g. the [[conceptual surface]] of the [[API]]) doesn't reference the service provider part ([[SPI]]). This advice optimizes for the common case where the number of people making calls into the [[API]] (e.g. using the [[ClientAPI]] part) is an order of magnitude bigger than those providing implementation of services (e.g. [[ProviderSPI]]). Also the service provider part is often more complicated and could scary the [[cluelessness]] out of newcomers.

[[Category:APIDesignPatterns:Clarity]] [[Category:APIDesignPatterns:Meta]]