It always helps when maintainers of a library or framework feel the pain of using it themselves. Then they become more open to address limitations of their own design. It's not users of (even of some obscure feature of) a library that shall "feel some pain every time they use it, to keep the usage as limited as possible". The maintainers should feel the pain. That helps them to get more Pragmatic and less academic!
--JaroslavTulach 06:02, 22 December 2021 (UTC)
The Genetics of an API design comes with own surprises: APIs shall not be copied, but only re-implemented. That's the paradox of copying an API!
--JaroslavTulach 06:29, 29 June 2021 (UTC)
ScienceOfAPIDesign is possible and can be almost as sharp as the most accurate science of all times - geometry. To achieve such sharpness it is better/easier/more useful to focus on binary compatibility in Java rather than source compatibility. Enhancing language can mitigate many issues, but regular library designers (mere mortals) can't change their language. We can only learn what advises the ScienceOfAPIDesign offers and use them in our daily policies. Or don't use them (but preferably knowing why).
Anyone willing to join the quest on making ScienceOfAPIDesign better and sharper?
--JaroslavTulach 06:08, 15 October 2020 (UTC)
I took a part in a tweetting about incompatibilities related to CharSequence.isEmpty() over the weekend and I asked myself a simple question: Is it possible to add a default method in a 100% binary compatible way? The newly written post provides the answer. Yes, adding default methods to interfaces in a 100% binary compatible way is possible at the end!
--JaroslavTulach 06:10, 30 September 2020 (UTC)
Designing an API that shall last? Then Never update tests! The need to update tests is a sign of an incompatible change.
--JaroslavTulach 04:05, 24 January 2019 (UTC)
Fighting with deadlocks is hard in normal code. In case of APIs it is even harder. Yet, the advice is simple Never hold a lock when calling a foreign code. See the typical example rewritten to be deadlock-free in the dedicated deadlock page.
--JaroslavTulach 07:11, 2 August 2018 (UTC)
Using Default Listener Methods is perfectly fine! Those who remember my recent arguments against using DefaultMethods in APIs maybe the surprised by this statement, but it has to be made. Looks like using Default Listener Methods doesn't violate any practices of good API Design.
Thanks Dušane, for pointing that out!
--JaroslavTulach 06:49, 19 April 2018 (UTC)
What does term Frontend mean to you? Tell us!
--JaroslavTulach 10:27, 6 April 2018 (UTC)
Recently I observed an incompatible API change and I received following explanation: Everything is OK, my ContinuousIntegration server is still green! In a shock I decided to write a philippic against ContinuousIntegration.
If you have to fix your tests in a significant way after making a change to your API, then you should think twice. Maybe such change isn't really compatible enough to become smoothly part of your framework. There is probably a lot of code similar to your tests out there and there is nobody to fix them as part of your refactoring. Better to learn and invest in keeping a bit of BackwardCompatibility.
In some sense: When designing APIs, relying only on ContinuousIntegration is bad!
--JaroslavTulach 14:16, 4 April 2018 (UTC)
Let me coin a new term: Turing speed - the real speed a programming language has. The speed of a general (e.g. Turing complete) computation. Read here why we need such classification.
--JaroslavTulach 08:40, 9 March 2018 (UTC)
Don't use default methods when designing your API. (For example when writing extensible visitor pattern) they just increase fuzziness and that is not what users of your API are searching for!
--JaroslavTulach 11:32, 5 March 2018 (UTC)
Designing for JDK9 is going to be more and more important when JDK9 is finally about to be released. However the modular design of Jigsaw brings in new challenges. Hear my story where I tried to update a library to run on headless JDK9: because there is a hidden catch - once you try to use PropertyChangeListener you get whole AWT/Swing user interface with that!
Learn how to avoid that: DesignForJDK9!
--JaroslavTulach 16:59, 14 August 2017 (UTC)
Two years ago I asked whether I can design Truffle API without being Domain Expert in the area of partial evaluation. Time has come to summarize my experience. I've written down list of eleven topics that I focused on mostly and (surprisingly even to myself) in most of the cases I was able to apply my APIDesign skills.
Read my TwoYearsWithTruffle essay to understand that once you are in a need of an API designer, you should talkback...
--JaroslavTulach 12:08, 2 August 2017 (UTC)
It is hard to push and pull at once in real life and people tend to know it. Yet I have witnessed many attempts that try to put both approaches into the same API at the same time and pretend those are equal. Small advice from a former API designer: don't do it!
For a longer advice please see the pull vs. push essay.
--JaroslavTulach 13:54, 16 June 2017 (UTC)
Is it JustCode that matters in a project or do projects need more? Is it necessary to have a bug tracking system or can we embed everything in the code? Is it better to keep snapshot of an API in the code or track it independently with additional tools?
Check my JustCode essay to see the benefits and drawbacks of both approaches.
--JaroslavTulach 08:54, 6 June 2017 (UTC)
Is Swing's openness reason for its so bad reputation?
--JaroslavTulach 10:37, 26 August 2016 (UTC)
I was invited to give a talk at CurryOn 2016 about Truffle called Become Polyglot by Learning Java!. It provoked tweets like: If you only watch one talk from @curry_on_conf, this one from @JaroslavTulach on Graal/Truffle is stunning. Here is its recording:
Or go to YouTube page.
--JaroslavTulach 05:33, 22 July 2016 (UTC)
There are two pitfalls of an APIReview. Either there is no code to review or there is too much code already written. The too little code case can easily be fixed. As Linus Torwalds use to say: Talk is cheap. Show me the code!
However what to do when APIReview brings in complex, complete solution with code almost ready for integration? Isn't that insulting? What kind of review one is supposed to perform then? Claim that the solution is completely wrong? That won't make the author happy. On the other hand coming for an architecture advice with fully working version isn't polite to reviewers either. Shall we read it as: Look how great I am! Approve the APIReview now!
Maybe there is a way to handle such review as well. But it remains to be seen if it works. Wish me luck.
--JaroslavTulach 13:38, 17 July 2016 (UTC)
Another variation on the topic of builder patterns. A builder that can track N essential attributes and whine (by throwing a checked exception) until all of them are specified.
Learn how to make your builder whine!
--JaroslavTulach 20:00, 26 June 2016 (UTC)
Hear the news! A new creature of the API design patterns rare species has been discovered. It looks like a builder pattern, but it ducks like something else. If you take a closer look you'll find out it is a chameleon! It changes its return type depending on its state.
Do you want to protect your own builder like a chameleon? Follow this link and learn the trick!
Once you discover the beauty, you'll not stop until you get your own chameleon builder into your own design!
--JaroslavTulach 09:34, 16 June 2016 (UTC)
Here is a nice extension to the builder pattern that allows one to control whether the final build() method throws a Checked IOException or not.
Enjoy this new addition to the list of APIDesignPatterns.
--JaroslavTulach 08:00, 13 June 2016 (UTC)
Checked exceptions are Java invention and many like to argue that they are the worst invention ever. I like exceptions and I like Checked exceptions. Today I am ready to explain why!
Do you believe people should only use runtime exceptions? That checked exception add too much overhead? Then you are wrong!
I agree that the concept of checked exceptions in Java has some drawbacks, but I am ready to explain how to overcome the restrictions and uncheck your checked exception whenever you want. Enjoy!
--JaroslavTulach 16:26, 6 April 2016 (UTC)
Truffle project is using Sigtest since today. I am maintaining the Truffle APIs since May, 2015 and I was applying my best knowledge and skills to design it properly. However I have to admit, I was operating in a blindness. Without having tests it is hard to decide whether your code change doesn't break your product. When designing API, it is important to know whether a change is or isn't backward compatible. Without a tool like Sigtest, it is almost impossible to do that manually!
Every project that designs an API needs an automated compatibility check. Learn what it takes to introduce such checks into your project by reading about the TruffleSigtest showcase!
--JaroslavTulach 10:34, 23 November 2015 (UTC)
Enforcing proper usage of an API is hard. One needs to strive for clarity, one can invent engineering solutions to the problem, but at the end clever hacker always find a way around it. But there is a cure: Let's choose our licenses wisely and scare the hackers with legal actions!
At the end it could also solve the famous sun.misc.Unsafe issue...
--JaroslavTulach 09:21, 15 June 2015 (UTC)
What is the relation between I18N and API design? Should API be internationalized and localized?
--JaroslavTulach 07:48, 31 May 2015 (UTC)
Domain Expert is a person who has knowledge of a particular system. With such knowledge it may seem easy to design APIs for the domain. However without understanding the API Paradoxes the quality of such API may not be high. It is likely going to cover the domain field, but the API usability or readiness for evolution will very likely suffer (unless such Domain Expert reads TheAPIBook first).
However can it work backwards? E.g. can one be just an API expert and then design good enough API without appropriate domain knowledge?
I am now participating in an experiment that will check that. OracleLabs guys asked me to help them design Truffle interoperability APIs. I do understand bit about Truffle, but certainly I am not a Domain Expert, yet I am supposed to design something as complicated as API to allow mixing of languages: imagine part of program written in Ruby, part in JavaScript, part in Java with objects floating between these languages without any borders!
This is a new situation for me: In case of NetBeans or in case of HTML/Java APIs, I was also the architect of the system. I knew it by heart. Now I barely understand how Truffle works and what makes it the fastest execution system for dynamic languages. My biggest fear is that I will design something that will be inherently slow.
On the other hand, I am not yet damaged with the expert knowledge. I can still see the system with new comer eyes - just like you, users of Truffle will. As such I can perform a usability study on me, at least initially.
If I can design easy to use APIs for Truffle, then I can create a perfect API facade around everything! Soon we'll have a chance to see whether one can be good API designer without being real Domain Expert. Soon we'll find out if API Design can be offered as a service!
Update from summer 2017: After TwoYearsWithTruffle I'd say there is a lot of things one can do to design API as a service without being a Domain Expert.
--JaroslavTulach 10:26, 17 May 2015 (UTC)
Brendan Eich, the inventor of JavaScript: I said 'JS is the x86 of the web' ... the point is JS is about as low as we can go..., here is a video to document the current JavaScript situation together with showing excellent demos as a proof:
--JaroslavTulach 07:00, 22 April 2015 (UTC)
My friends keep talking about the greatness of Gradle. It is hard to stand it, especially knowing there is a significant flaw introduced in Gradle's core.
The flaw is so huge that I rank Gradle along Ant. Into Ant-age!
--JaroslavTulach 15:56, 15 March 2015 (UTC)
BinarySelection plays (except having its classical search meaning) an important role in theory of HR management. It defines what happens when employees are leaving the employer (either voluntarily or after being fired):
BinarySelection means, that "ones" leave and "zeros" stay.
I mention this definition whenever we chat about life of software developers and it always generates grin smile. Of course, because it is so true! I can confess that as for last seventeen years I have been sticking with my job surviving any layoffs and acquisitions: I've seen so many "ones" leaving, but the rest of us is still marching on!
--JaroslavTulach 06:20, 23 December 2014 (UTC)
When I was younger I used to believe that having invokeDynamic instruction in JVM can be beneficial. Now, few years later and after spending time to implement lambdas in my Bck2Brwsr VM and seeing things from the other side I have to admit I was wrong. invokeDynamic is wrong idea (especially for implementation of lambdas).
It is JavaOne time, I have a talk about my Bck2Brwsr together with Niclas from RoboVM, so let's show I understand what is wrong with JVM and start a little rant! I need something from the JDK guys, so let's give them a reason to welcome me with open arms when we see each other in San Francisco:
InvokeDynamic should have never been added to Java and should be removed from the specification. Read why...
--JaroslavTulach 12:50, 25 September 2014 (UTC)
Hear the news: Sources in ZIP format are back!
My Hudson server crashed in early months of 2014. I had to configure it from scratch. While doing so, I forgot to configure the job to produce apidesign.zip file with sources. Has anyone noticed? Nobody sent me an email! Just yesterday Jáchym, my co-worker, who I torture by forcing him to read TheAPIBook and become good API designer, stopped in my office and timidly asked: Where can I get the sources? There is no ZIP file!
For a while I tried to blame him for not using Mercurial, but after a while I realized the problem is on my side. As a result, the zip file with sources is back as of Aug 8, 2014. Will anyone use them? It would be nice as reading Practical API Design book without having whole sources at your hand is like trying to understand Swing just by reading its Javadoc.
--JaroslavTulach 11:16, 8 August 2014 (UTC)
Epistemology of software design by Nathan is online! I greatly recommend it to everyone who wants to produce software that lasts! After all those years with NetBeans I can only confirm everything Nathans describes!
If you want to stop being a software engineer and become software architect, epistemology of software design is one of the things you have to memorize!
--JaroslavTulach 20:01, 15 May 2014 (UTC)
By lowering profile of our libraries, we can make them more ready for JDK8. Here is few patterns one can use to adopt own library to JDK8 profiles.
Lower your profile, let (your library usage) get higher!
--JaroslavTulach 11:40, 23 March 2014 (UTC)
As paragraph on page 154 shows, it is not easy to find out what a meaning of it, this and that may be. Thanks Yoshiki for contributing this first Errata for Chapter 9!
--JaroslavTulach 10:53, 11 February 2014 (UTC)
How do you recognize Good Advice? We already know what a good technology is, can we use the same concept to evaluate whether an advice is good or not? Let me answer that by a quote from TheAPIBook which Yoshiki asked about:
Part 1 presents all of API design as a scientific discipline with a strong rational background, not as the art that it sometimes pretends to be. It defines terminology and initial prerequisites that can objectively help us measure if an API design is good. These rules try to be language neutral and applicable to any programming language, not just Java. The theory is unlikely to be complete. Other principles of API design exist elsewhere or are still waiting to be discovered.
However, that should not scare us, as Chapter 1 gives us a tool to evaluate the quality of various principles to find out whether a certain piece of advice helps us design better shared libraries and their APIs or not. It gives us the grand meta-principle: selective cluelessness. This cluelessness is a tool that can measure whether various goals really help. That’s because if they allow people to know less while achieving more and building better software systems more easily, then this advice is good. There is a need for this advice, especially in the future, when software systems will outsize the intellectual capacity of any of their designers.
"this advice" is a reference to advice mentioned in "to find out whether a certain piece of advice helps us design better shared libraries". To rephrase: any advice that helps users increase cluelessness is good and it will be even more valuable in the future when we start to build even bigger systems.
--JaroslavTulach 08:04, 6 February 2014 (UTC)
Language that you speak and write defines what you can think and reason about. The worse language you can use the better programmer you are. Right?
--JaroslavTulach 13:02, 16 October 2013 (UTC)
References and WeakReferences play important role when designing an API contract or building a framework. Are you sure you use them properly? Read about problems we had when messing with WeakReferences in the Lookup API.
--JaroslavTulach 08:50, 11 October 2013 (UTC)
A curious translator of my book asked me about project Harmony. That motivated me to sit down and write an incomplete and mostly wrong history of open source java implementations. While incomplete (for example it does not talk by whom Harmony was founded and why), it explains why JDK8 is/will be a huge step forward and what will be its most important feature. Btw. if you thought lamdas, you were wrong.
--JaroslavTulach 14:54, 12 August 2013 (UTC)
Short introduction to accurate, agile, modern, reliable, flexible, optimistic, forward looking, experience based, projective planning methodology.
--JaroslavTulach 15:10, 19 March 2013 (UTC)
Those of you who heard about Platon in school probably also hard about his allegory of a cave (at least I did when I was at high school). It is not often easy to imagine what Platon meant by the cave, shadows, etc. Luckily (at least for developers who know what geometry is), there is a better explanation which which explains Platon's theory of ideas via geometry.
This geometric way of explaining [[ideas was much easier for me to swallow. That is why I decided to share it here.
--JaroslavTulach 08:45, 21 January 2013 (UTC)
Here are selected notes from my favorite write up by Edsger W. Dijkstra (the guy that invented semaphore). Few decades has passed since the initial publication and the difference between U.S. and Europe may not be as sharp anymore. Still, a lot of Dijkstra's comments apply - especially when it comes to the clash between programmers educated in soft vs. real science schools!
Btw. should this kind of analysis be found interesting, I can share another one: Why our U.S. friends can't read maps and are not aware of that. Just let me know if I should publish it.
--JaroslavTulach 11:56, 17 January 2013 (UTC)
A theoretical observation about a hammer with application to real world scenario as well as software user interface design.
--JaroslavTulach 13:37, 12 November 2012 (UTC)
A nice clash between real world and academic attempts to describe it can be seen on the case of TransitivityOfIncompatibleChange. While such transitivity is an easy to grasp concept, it is too simplistic and often too hard to apply for the real world of software dependencies. It took me a while to understand its alternative, but now I think I see it.
Last week I had a presentation about the topic of NP-Complete problems in module dependencies at MatFyz and one of the questions was: Why am I not using TransitivityOfIncompatibleChange in case of repositories with RangeDependencies? Well, I don't as it does not have a clear meaning. But the question forced me to sit and write the answer down.
Hopefully not only MatFyz guys find the essay useful.
--JaroslavTulach 02:00, 7 November 2012 (UTC)
Just a few thoughts about the difference between language and a framework (plus a wish how Java should evolve).
--JaroslavTulach 09:06, 18 October 2012 (UTC)
Today I am ready to announce great news. My new book about 20 API Paradoxes is now publicly available. I'd like to thank everyone who helped me get it to e-readers all over the globe. Jeff corrected my English and made the structure of the book more consistent. Clay stopped me when I wanted to expand the scope and delay the publication. And, most importantly, Clay is responsible for this fantastic cover:
I asked Clay to select cover that would somehow reflect my relation with my home and I am glad he decided to use painting of Josef Lada - a painter of my childhood.
I hope you like the cover too. And not only that, I hope you'll like the content as well. Buy & enjoy!
--JaroslavTulach 18:11, 11 October 2012 (UTC)
James Borowski on 100th Monkey principle:
Found reading some stuff on your site really interesting. I have not finished reading yet, so, forgive me if you already know this, but I was reading the article DiamondsVsStars and wondered as I read your comments regarding the "something in the air" as people around the world all discover something at the same time, if you were aware of the 100th Monkey principle?
There are different versions of the tale, but essentially, there was an island with a load of monkeys that learnt a trait one at a time of how to knock nuts with a rock to get inside them (other versions of the story are about learning to wash them, but the principle is the same). It took a while for monkeys to copy each other, one at a time, and the speed of uptake was essentially linear and at a fixed rate until they reached the 100th Monkey. At this point, every monkey on the island, and every monkey on the three neighbouring islands all started the same trait, almost instantly. The point is: A species appears to be connected at some vibrational level to the extent that they share certain thought processes/notions. There is a tipping point (apparently this is the square route of 1% of the population pool / or 100 monkeys ) where once reached, this information is availiable to all. Almost as if an entire species are listening on the same multicast address.
Anyway, hope you find as interesting as I found your stuff. For more info see 100th Monkey at wikipedia.
Thanks, for sharing this observation, James!
--JaroslavTulach 19:29, 8 August 2012 (UTC)
Here are some thoughts on the difference between 100% BackwardCompatibility and their slightly more practical variants.
--JaroslavTulach 12:13, 31 July 2012 (UTC)
Follow
