Our first decided ADR was to use JSpecify as API to annotate the contract of Operaton’s API in regard of nullability. Users and developers should know whether to expect that methods can return null or not and whether arguments to methods must be non null or not.
We have now started implementing this. Operaton’s code base is huge, and it is impossible to do this in a single shot. So incrementally we are working through the API to annotate everything, starting with the core modules.
AI is supportive here, but we do not rely on AI to refactor the API. Each annotation must be handcrafted to understand why it was placed. Our massive test code base and AI help us to find wrong assumptions. But even with that we cannot completely guarantee that there are no errors.
Why this becomes important: The annotations do not change the API, but quite often in the code methods are called which require that certain arguments must not be null. On the caller side the argument may be possibly null because a variable might result from a method that can be null. Obviously de facto the result is not expected to be null, but static code analysis will raise warnings which we need to resolved. To do so, we call at those places Objects.requireNonNull() before passing the possibly null variable as argument that must not be null. In the end, we have several now hard coded checks that could raise a NullPointerException (requireNonNull raises it) when some variable is unexpectedly null. Although we are doing our very best there is a slight chance that you could face such new exceptions. If so, please report that.
At this moment, 25% of the engine’s API and 12% of the total API is annotated. This will be ongoing with the aim to cover most of the engine’s API until the 2.2 release in October. Likely we are not done then completely, thus efforts will close for 2.3 in April.