Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Confusing sentence in Design Principles docs #1740

Open
InmanCochrane opened this issue Jan 22, 2025 · 1 comment
Open

Confusing sentence in Design Principles docs #1740

InmanCochrane opened this issue Jan 22, 2025 · 1 comment

Comments

@InmanCochrane
Copy link

I know this is trivial, and 7 years old from the Akka fork, but I was perplexed by this sentence in the Design Principles page:

With this historical knowledge and context about the purpose of the standard – being an internal detail of interoperable libraries - we can with certainty say that it can't be really said that a direct _inheritance_ relationship with these types can be considered some form of advantage or meaningful differentiator between libraries.

I tried to parse my way through,

can
  with certainty
    it can't
      really be that X
        can be considered
          P or
          Q

and think I've landed on a qualifier-free simplification of, "A direct inheritance relationship with these types cannot be considered some sort of advantage nor meaningful differentiator between libraries."

Is that what this is trying to say? I acknowledge that qualifiers can be important, so that's why I'm not submitting a PR to use that new text, but I'm suggesting that someone who understands this better try to rephrase that sentence or paragraph so that it's easier to follow.

@raboof
Copy link
Member

raboof commented Jan 27, 2025

Yes, I think you understood it correctly - this is further confirmed by the next sentence

Rather, it could be seen that APIs which expose those SPI types to end-users are leaking internal implementation details accidentally.

I don't remember the history, but I think there were some other implementations that were marketing themselves as supporting Reactive Streams "more natively" because they were directly extending those classes, which doesn't really make sense.

Perhaps we should make it a bit more direct, and replace those two lines with something like:

In other words, these classes are intended to be an internal detail of interoperable libraries. While some other libraries expose the SPI types directly to end users, for example by inheriting from them, you could say this leaks an internal implementation detail.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants