[xwiki-devs] [Discussion] Should our components be user-public or not?
Hi, We need to decide if we want our component implementations (the class implementing the interface of a component) to be user-public or not. By user-public I mean allowing user of the code to use them (for composition, for inheritance). The alternative is to make them internal and forbid users to import them. This means moving them to an internal package (see http://www.eclipse.org/articles/ article.php?file=Article-API-Use/index.html) and telling our users that they change anytime so they shouldn't use them. This would also mean we wouldn't have to go through a deprecation stage to make any change to our components. My initial reaction to this was that they should be public but the more I think about it the more I think making them internal might be the best choice. WDYT? Thanks -Vincent
+1 for internal On Fri, Aug 22, 2008 at 11:05 PM, Vincent Massol <[email protected]> wrote:
Hi,
We need to decide if we want our component implementations (the class implementing the interface of a component) to be user-public or not.
By user-public I mean allowing user of the code to use them (for composition, for inheritance). The alternative is to make them internal and forbid users to import them. This means moving them to an internal package (see http://www.eclipse.org/articles/ article.php?file=Article-API-Use/index.html) and telling our users that they change anytime so they shouldn't use them. This would also mean we wouldn't have to go through a deprecation stage to make any change to our components.
My initial reaction to this was that they should be public but the more I think about it the more I think making them internal might be the best choice.
WDYT?
Thanks -Vincent
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
+1 for internal
Hi,
We need to decide if we want our component implementations (the class implementing the interface of a component) to be user-public or not.
By user-public I mean allowing user of the code to use them (for composition, for inheritance). The alternative is to make them internal and forbid users to import them. This means moving them to an internal package (see http://wwwâ.eclipse.oârg/articleâs/ article.âphp?file=Aârticle-APIâ-Use/indexâ.html) and telling our users that they change anytime so they shouldn't use them. This would also mean we wouldn't have to go through a deprecation stage to make any change to our components.
My initial reaction to this was that they should be public but the more I think about it the more I think making them internal might be the best choice.
WDYT?
Thanks -Vincent
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
Vincent Massol wrote:
Hi,
We need to decide if we want our component implementations (the class implementing the interface of a component) to be user-public or not.
By user-public I mean allowing user of the code to use them (for composition, for inheritance). The alternative is to make them internal and forbid users to import them. This means moving them to an internal package (see http://www.eclipse.org/articles/ article.php?file=Article-API-Use/index.html) and telling our users that they change anytime so they shouldn't use them. This would also mean we wouldn't have to go through a deprecation stage to make any change to our components.
My initial reaction to this was that they should be public but the more I think about it the more I think making them internal might be the best choice.
Private. The component's description (the interface) is enough. If we need a more detailed "interface", then maybe we should either create a new component, or redesign the code using that component. Implementations should stay hidden. -- Sergiu Dumitriu http://purl.org/net/sergiu/
On Aug 24, 2008, at 10:56 PM, Sergiu Dumitriu wrote:
Vincent Massol wrote:
Hi,
We need to decide if we want our component implementations (the class implementing the interface of a component) to be user-public or not.
By user-public I mean allowing user of the code to use them (for composition, for inheritance). The alternative is to make them internal and forbid users to import them. This means moving them to an internal package (see http://www.eclipse.org/articles/ article.php?file=Article-API-Use/index.html) and telling our users that they change anytime so they shouldn't use them. This would also mean we wouldn't have to go through a deprecation stage to make any change to our components.
My initial reaction to this was that they should be public but the more I think about it the more I think making them internal might be the best choice.
Private. The component's description (the interface) is enough. If we need a more detailed "interface", then maybe we should either create a new component, or redesign the code using that component. Implementations should stay hidden.
Yes but this was not the problem. The problem is for example if a user wants to create, say, a XHTML2 macro based on our XHTML macro. He'll have to have it injected for example (or inherit from it). In both cases this means exposing the internal package (in components.xml or in the import). Thus if the class name is changed for example, it'll break the user. Same for protected methods which will also break backward compat if used and modified. But I think this is ok. It just means our component implementations cannot be reused since they are private. We'll just need to make this very clear. Thanks -Vincent
Vincent Massol wrote:
On Aug 24, 2008, at 10:56 PM, Sergiu Dumitriu wrote:
Vincent Massol wrote:
Hi,
We need to decide if we want our component implementations (the class implementing the interface of a component) to be user-public or not.
By user-public I mean allowing user of the code to use them (for composition, for inheritance). The alternative is to make them internal and forbid users to import them. This means moving them to an internal package (see http://www.eclipse.org/articles/ article.php?file=Article-API-Use/index.html) and telling our users that they change anytime so they shouldn't use them. This would also mean we wouldn't have to go through a deprecation stage to make any change to our components.
My initial reaction to this was that they should be public but the more I think about it the more I think making them internal might be the best choice.
Private. The component's description (the interface) is enough. If we need a more detailed "interface", then maybe we should either create a new component, or redesign the code using that component. Implementations should stay hidden.
Yes but this was not the problem. The problem is for example if a user wants to create, say, a XHTML2 macro based on our XHTML macro. He'll have to have it injected for example (or inherit from it). In both cases this means exposing the internal package (in components.xml or in the import). Thus if the class name is changed for example, it'll break the user. Same for protected methods which will also break backward compat if used and modified.
But I think this is ok. It just means our component implementations cannot be reused since they are private. We'll just need to make this very clear.
I understand now. Yes, the implementations should not be for the public, meaning that the developers of the official platform can use (inherit) them internally, and we can change whatever we want between releases, but third party code should never rely on these implementations. -- Sergiu Dumitriu http://purl.org/net/sergiu/
So far: - sergiu: +1 for internal - thomas: +1 for internal - marius: +1 for internal - vincent: +1 for internal but not as strongly as the others above ;) Ok so I've added it to our best practices there: http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices http://dev.xwiki.org/xwiki/bin/view/Community/CodeStyle Thanks -Vincent On Aug 22, 2008, at 11:05 PM, Vincent Massol wrote:
Hi,
We need to decide if we want our component implementations (the class implementing the interface of a component) to be user-public or not.
By user-public I mean allowing user of the code to use them (for composition, for inheritance). The alternative is to make them internal and forbid users to import them. This means moving them to an internal package (see http://www.eclipse.org/articles/ article.php?file=Article-API-Use/index.html) and telling our users that they change anytime so they shouldn't use them. This would also mean we wouldn't have to go through a deprecation stage to make any change to our components.
My initial reaction to this was that they should be public but the more I think about it the more I think making them internal might be the best choice.
WDYT?
Thanks -Vincent
So far: - sergiu: +1 for internal - thomas: +1 for internal - marius: +1 for internal - vincent: +1 for internal but not as strongly as the others above ;) Ok so I've added it to our best practices here: http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices http://dev.xwiki.org/xwiki/bin/view/Community/CodeStyle Thanks -Vincent On Aug 22, 2008, at 11:05 PM, Vincent Massol wrote:
Hi,
We need to decide if we want our component implementations (the class implementing the interface of a component) to be user-public or not.
By user-public I mean allowing user of the code to use them (for composition, for inheritance). The alternative is to make them internal and forbid users to import them. This means moving them to an internal package (see http://www.eclipse.org/articles/ article.php?file=Article-API-Use/index.html) and telling our users that they change anytime so they shouldn't use them. This would also mean we wouldn't have to go through a deprecation stage to make any change to our components.
My initial reaction to this was that they should be public but the more I think about it the more I think making them internal might be the best choice.
WDYT?
Thanks -Vincent
participants (4)
-
Marius Dumitru Florea -
Sergiu Dumitriu -
Thomas Mortagne -
Vincent Massol