Topic on Talk:Best practices for extensions/Flow

Done, per Stable interface policy.

I propose to add the following to the "Don't" section:

• MUST NOT: subclass (extend) any class defined by MediaWiki core, unless that class is explicitly documented to allow subclassing by extensions.

The reason for this is that protected methods are not part of our stable interface per the Deprecation policy, so such subclasses may break without warning. The relevant section of the deprecation policy reads:

[...] the stable part of the PHP API is comprised of all code that is explicitly marked public, and has been included in at least one stable release. In addition, some classes expect to be subclassed in extensions; in those cases protected functions also are included in the API. These classes should have a note in their documentation comment that they expect subclassing. If no note is present, it SHOULD be assumed that the class is not expected to be subclassed.

I'm tempted to even extend this to implementing interfaces. Not all interface declarations are intended as extension points, and not all of them should be considered stable. If we go that far, we should also add:

• MUST NOT: implement any interface declared by MediaWiki core, unless that interface is explicitly documented to allow implementation by extensions.

+1 to both suggestions from my side.

I, personally, find it a really helpful rule-of-thumb to consider all classes to be final, except otherwise stated. The effect of this restriction is pretty much the same as you suggest: one can not extend anything, except it is allowed. The only reason we are not literally marking all our code as final is that it would be cumbersome and error-prone. But we should still threat it like it is.

This has been superseded by the Stable interface policy.