[
https://issues.apache.org/jira/browse/JSPWIKI-38?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12659328#action_12659328
]
Janne Jalkanen commented on JSPWIKI-38:
---------------------------------------
The Ruby on Rails folks have taught an important lesson: convention over
configuration. I think this is very powerful, and Stripes uses the same
paradigm as well by defaulting to certain package naming conventions for its
ActionBeans: in fact, they force you to have an extra level of depth in your
package naming by assuming your ActionBeans lie in the ".stripes." or
".action." packages. In the same vein, I think the separation of the API
classes into a separate hierarchy of their own does make sense by encoding the
fact that they *are* API classes directly into the package names themselves.
Much like the "plugin" in the package name means that these are plugins.
Now, I am not entirely certain whether moving practically all of our classes
(save a few odd stranglers, perhaps ten or so for 3.0) into a .private
-namespace makes sense either. It is certainly not the simple solution that
Andrew alluded to above, and will probably confuse developers. Think about the
two different messages: "You may use anything in the api-package, and that will
be stable." vs "You may use anything under org.apache.jspwiki.* EXCEPT for the
packages under private, and all those will be stable (except those
aforementioned packages)" There's a subtle difference, and I would much rather
go for the first one than the second one. Easier to communicate, easier to
code, easier to understand and easier to build scripts for. And, while
creation of an "impl" -package might keep third party developers happier, it
will annoy our current core developer base by introducing an extra layer.
After all, *we* have to deal with those 350+ classes all the time.
However, we could make a cosmetic change by creating a JSPWiki API subproject,
call it "jspwiki-api". It's really all about switching a period to a dash, but
it does not create any further nesting levels (though since most developers
these days *do* use IDEs, I don't think any extra levels are really a problem).
So, we would have "org.apache.jspwiki" with the implementation, and
"org.apache.jspwiki-api" for the API.
Other possibility is to treat these in reverse, but I don't really like the
"impl" or "private" names. There would need to be a better naming convention.
I guess my main objection is that since the aim of this project is to produce
the wikiengine itself, not the API, I really don't like the idea that we give
the API the first-class citizen treatment and force the actual implementation
to some second-tier packages. The org.apache.jspwiki -package should really be
about the JSPWiki *engine*, not an abstract API class set. If we had set out
to do to create an API definition, then yes, then obviously we would do things
differently, but I don't think API creation has ever been more than just an
issue on this tracker.
If we wish to have a top-level package for the API, then perhaps a subproject
with own dedicated package name might make most sense.
> Rename packages to "org.apache.jspwiki"
> ---------------------------------------
>
> Key: JSPWIKI-38
> URL: https://issues.apache.org/jira/browse/JSPWIKI-38
> Project: JSPWiki
> Issue Type: Task
> Reporter: Janne Jalkanen
> Assignee: Janne Jalkanen
> Fix For: 3.0
>
>
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
