I'm +1 for this refactoring, though I probably won't have time to help. Cheers, Nick
On 10/31/03 1:00 PM, "Vincent Massol" <[EMAIL PROTECTED]> wrote: > Hi, > > I'd like to perform a full overhaul of our package organization. The > reason is that we are currently not showing our users what API is public > and what API is not public. Unfortunately, Java does not provide a > built-in solution for this. > > I'd like to propose to use the scheme used in Eclipse development (see > http://www.eclipse.org/articles/Article-API%20use/eclipse-api-usage-rule > s.html). Paraphrasing Jim: > > ----- proposal start here ----------- > > To try to draw the line more starkly, the code base for the platform is > separated into API and non-API packages, with all API elements being > declared in designated API packages. > > - API package: a JavaT package that contains at least one API class or > API interface. The names of API packages are advertised in the > documentation for that component; where feasible, all other packages > containing only implementation details have "internal" in the package > name. The names of API packages may legitimately appear in client code. > For the Cactus project, these are: > org.apache.cactus.foo.* - API > org.apache.cactus.foo.internal.* - not API; internal implementation > packages > org.apache.cactus.sample.* - not API; these are examples > > - API class or interface: a public class or interface in an API package, > or a public or protected class or interface member declared in, or > inherited by, some other API class or interface. The names of API > classes and interfaces may legitimately appear in client code. > > - API method or constructor: a public or protected method or constructor > either declared in, or inherited by, an API class or interface. The > names of API methods may legitimately appear in client code. > > - API field: a public or protected field either declared in, or > inherited by, an API class or interface. The names of API fields may > legitimately appear in client code. > > Everything else is considered internal implementation detail and off > limits to all clients. Legitimate client code must never reference the > names of non-API elements (not even using Java reflection). In some > cases, the Java language's name accessibility rules are used to disallow > illegal references. However, there are many cases where this is simply > not possible. Observing this one simple rule avoids the problem > completely: > > - Stick to officially documented APIs. Only reference packages that are > documented in the published API Javadoc for the component. Never > reference a package belonging to another component that has "internal" > in its name---these are never API. Never reference a package for which > there is no published API Javadoc---these are not API either. > > ------- end of proposal ----------- > > Committers, do you agree to refactor our packages to follow these rules? > > Here's my +1 > > Thanks > -Vincent > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
