Skip to main content
copy-edited
Source Link
Deduplicator
  • 9.1k
  • 5
  • 33
  • 52

If you publish a normal function, you give a one-sided contract:
What does the function do if called?

If you publish a callback, you also give a one-sided contract:
When and how will it be called?

And if you publish an overridable function, it's both at once, so you give a two-sided contract:
When will it be called, and what must it do if called?

Even if your users aren't abusing your API (by breaking their part of the contract, which might be prohibitively expensive to detect), you can easily see that the latter needs far more documentation, and everything you document is a commitment, which limits your further choices.

An example of reneging on such a two-sided contract is the move from show and hide to setVisible(boolean) in java.awt.Componentjava.awt.Component.

If you publish a normal function, you give a one-sided contract:
What does the function do if called?

If you publish a callback, you also give a one-sided contract:
When and how will it be called?

And if you publish an overridable function, it's both at once, so you give a two-sided contract:
When will it be called, and what must it do if called?

Even if your users aren't abusing your API (by breaking their part of the contract, which might be prohibitively expensive to detect), you can easily see that the latter needs far more documentation, and everything you document is a commitment, which limits your further choices.

An example of reneging on such a two-sided contract is the move from show and hide to setVisible(boolean) in java.awt.Component.

If you publish a normal function, you give a one-sided contract:
What does the function do if called?

If you publish a callback, you also give a one-sided contract:
When and how will it be called?

And if you publish an overridable function, it's both at once, so you give a two-sided contract:
When will it be called, and what must it do if called?

Even if your users aren't abusing your API (by breaking their part of the contract, which might be prohibitively expensive to detect), you can easily see that the latter needs far more documentation, and everything you document is a commitment, which limits your further choices.

An example of reneging on such a two-sided contract is the move from show and hide to setVisible(boolean) in java.awt.Component.

Source Link
Deduplicator
  • 9.1k
  • 5
  • 33
  • 52

If you publish a normal function, you give a one-sided contract:
What does the function do if called?

If you publish a callback, you also give a one-sided contract:
When and how will it be called?

And if you publish an overridable function, it's both at once, so you give a two-sided contract:
When will it be called, and what must it do if called?

Even if your users aren't abusing your API (by breaking their part of the contract, which might be prohibitively expensive to detect), you can easily see that the latter needs far more documentation, and everything you document is a commitment, which limits your further choices.

An example of reneging on such a two-sided contract is the move from show and hide to setVisible(boolean) in java.awt.Component.