Home   Info   DevZone   Wiki  
UsersWeb  |  MainWeb  |  InfoWeb  |  DevZoneWeb  |  SupportWeb
ClassPrefixPoll ] [ not logged in ] [ Web: Imported ] goto:  options
[ get info on or edit ] login or new user ] [ list of topics, hubs & nodes, or recent changes ]

JOS folks, speak out!

YESNO
MatthewCaswellAveryRegier
BorneMaceDigiGod
StefanReichVivekVenugopalan
JohnDeCuirWeoLopez
WaynePierceBorkoJandras
AlexisPetrouniasJeroenVanGelderen
MasonZhwitiMarioCormier
MichaelNygardStefanBorg
StephenMarneyMichaelRichter
DanielHarrisMarkKuschnir
RyanSullivanBrillPappin
SebastianGolze
BenKnowles
RanieriArgentini

JosCommunicationBusArchitecture and StefansAPIStructureProposal both define JOS specific classes/interfaces. They prefix each name with "Jos": JosServiceRegistry, JosConnectionPublisher, ...

Do you think this is necessary? Or should the JOS API classes be named ServiceRegistry, ConnectionPublisher, etc.? (Note: We're speaking of the "exposed" JOS classes only, not internal ones.)

Advantages of the prefix are:

Disadvantages are: What is your opinion? "Jos" prefix or not? Please answer on this page, so we can decide democratically (it's the first time we do that at JOS, isn't it?).

--StefanReich, 15-Apr-98


My vote is NO. JOS system classes & interfaces will be identified as JOS specific by their package names. Adding "JOS" to the start of each class is simply redundant. Naming conflicts in other packages is handled in Java by the requirement that if two classes in different packages have the same name, and you import both packages, you must simply specify the full package name in the class file.

-- AveryRegier 15-Apr-98


My vote is YES. Naming conflicts are not a problem because of the reasons Avery has pointed out. However, I believe it is worth doing simply because of clarity. If you are reading someone elses source code and are unfamiliar with the classes defined by JOS, it would be a real pain to determine whether a particular class has been defined in "org.jos.", or "com.wibble.". Prefixing with "Jos", is not a lot extra to type and makes it instantly recognizable that this is a JOS class.

-- MatthewCaswell 15-Apr-98


I agree with Matthew. The Jos is very simple to tack on, and as these classes may very well be used outside of the JOS project it is also nice to be able to identify their use by name. It isn't a big deal really, and whether we put the Jos on there or not could also be left up to the coder. I think that as long as your code works, you can call it anything you want to.

-- BorneMace 15 April 1998


NO. As Avery states, the package names are sufficient to distinguish JOS classes from other classes. The extra prefix is just clutter. I also think the argument about "knowing" they are JOS classes is flawed. Can you use any API without knowing the classes? In any development environment more sophisticated than "vi", you can always jump from the class name in use to its definition. Consider an analogous situation: When you import classes from JGL, KLGroup, or IBM, they have no prefix on every class name. Instead, they rely on the package name to disambiguate the name. We should definitely do the same.

(BTW, I expected more responses. I guess most of us in the US are a little distracted today. (For non-US people, its tax day here. (Have you ever noticed that deeply nested parenthetical remarks in written language are unique to developers?)))

-- MichaelNygard, 15 Apr 1998


There can be instances where package de-ambiguity of class names is not enough. For example, say I write a class called a Registry, however in another package somewhere(that I am using) there is another object called Registry, well look at my situation now, I have to completely qualify my use of Registry (or at least one use of Registry) and if I tried to import both packages I suppose when I created an instance of a Registry it woulc create one based on the first package imported(based on the assumption that the packages are parsed in the same order they are imported). So a JosRegistry and a Registry could be used happily together, for ever more. I know things like this don't happen much, but why take the chance? Are three letters really that much of a hassle?

And agreed on that last comment Michael, when you see nested parens in someone's statment you can generally assume they are a coder, in my experience.

-- BorneMace 16 April 1998


Michael states - "Can you use any API without knowing the classes?". The answer is you cannot write code without knowing the API. However it is quite possible that you may read code without knowing that API. Hopefully the JOS API will have class names that suggest what they do. Adding the JOS prefix, clarifies further the intended function of the class.

-- MatthewCaswell 16 April 1998


NO. I hate typing --DigiGod 16 April 1998
NO. Since I am the guy who initally started this debate with Stefan, let me restate my issues here
  1. These extra characters provide only a false sense of security in terms of unambiguous names since if we have org.jos.foo.JosRegistry and org.jos.bar.JosRegistry then nothing has been solved.
  2. Readability is not enhanced since any application that uses JOS classes will be using them a lot and so a JosThis and a JosThat strewn all over the place does no buy the programmer anything. Please make good class names to better inform the users.
  3. If for some reason, in the next JDK, sun has the prefix Jos or JOS for any one of their classes, then guess who has to make changes. This will break our naming consistency. Granted that it is not a common occurance this is still an issue.
  4. Java's way of packaging is probably the best way of doing things. Packages + classes. I am sure Sun will make all necessary changes in the language to fix any shortcomings with this design.
  5. It will resemble the microsoft MFC hierarchy (CObject). Need I say more?

VivekVenugopalan


I still haven't seen another real disadvantage beyond people who think 3 extra letters in a class name is just way too much.

-- BorneMace 17 April 1998


The idea I had in mind when I introduced the prefix was to stress the org.jos.api classes' special character. They are all abstract, but know where an implementation is found.

So, when you see a class named "Jos...," you know that an implementation has to be registered before the class can be used.

The org.jos.api classes are special in another way: they are the only JOS classes visible to applications. It's an easy rule to remember: classes with arbitrary names are JOS-internal and can be changed between releases; classes starting with "Jos" belong to the API and have to conform to certain rules (StefansAPIStructureProposal) in order to ensure backwards compatibility.

These are all "psychological" reasons. But what do you expect, class names are for humans, not for machines.

Despite the current majority against the prefix, I'm still very much in favor of it.

--StefanReich, 17-Apr-98


I vote YES; added clarity is always worth it, regardless of extra typing required. Trust me, when scanning through tons of code, you'll be happy the three letters are there.

--JohnDeCuir, 4-17-98


NO. Sometimes it's harder to do it right.

-- StephenMarney, 19 Apr 1998


YES, definitely! It makes more sense having the JOS in the class name instead of only having it in the package. When you talk about the System class or the SecurityManager you obviously mean the one located in java.lang. However, with JOS, how will you refer to it? You will say the JOS System and the JOS SecurityManager. So, for reasons of clarity and ease of use, we put the JOS there. And trust me, developers spend more time thinking and browsing the Web for specifications and algorithms than typing in code. And we have visual editors if it's that tiring!

-- AlexisPetrounias, April 20, 1998


Yes, I don't see where this can hurt anything.

--WaynePierce 20 Apr 98


Wow! What to do, what to do? There are lots of compelling arguments going both ways. I say yes, for several reasons:

True, it will be redundant when you're looking at the class list or API, but reading/writing the code will be where most people see the class names.

However, all that being said, I really don't think it matters one way or the other. The important thing is to pick a way and stick with it. If we DO go with it, then OK. If we DON'T go with it, then that's fine too, but we'll just have to use full package names when in need of clarity. So, I vote YES.

--MasonZhwiti


Hmmm. Well. This is a more subtle issue than I originally thought. Reading the statements from Alexis and Stefan, which emphasize that these mark the exposed classes got me thinking about this issue all over again. As a result, I'm changing my vote to YES. Here's why:

When crafting an API, you must consider both sides of the interface. From the clients' perspective, the extra characters might be clutter, or they might be useful. That would seem to be largely a matter of taste. From the implementers' perspective, however, things are a little different. One of the most difficult parts of constructing a solid API is maintaining discipline. Sometimes, classes will sneak out from behind your interface and become unintentionally visible. Other times, the implementer might be tempted to take shortcuts in a classes interface, or change existing methods to be more consistent with the evolution of an API. (I know we've all done it.) Obviously, a system API had better be much more stable than your typical internal interfaces.

All of which leads me to this point: While the "Jos" prefix might be of debatable value to the clients of an API, it serves as a marker to remind the implementer to maintain discipline. If I am working on anything named "Jos*", I know that changes to the interface must never be made lightly.

In addition, if I take over a package with dozens of classes, it will be apparent which ones are meant to be exposed. (The "public" access specifier is not enough; in many cases classes must be public for implementation reasons, not because they should be exposed.)

An interesting debate!

-Michael Nygard, 21 April 1998


Thank you, Michael, for completing what I started! You clarified what I wanted to say.

The essential point is actually that all "public" classes (and only them) are to carry the prefix. ("public" not as a Java keyword, but in the sense of "visible to applications.")

--StefanReich, 22-Apr-98


I'm changing my vote to YES. I can see how the prefix will serve to create a 'namespace' which serves a variety of purposes (which others have outlined) and there is no easy other way to create such a 'namespace' in java. When done (and if YES wins) someone might clearly wrap up what specific conditions should hold to use the prefix. And we'll have to stick to the conditions strictly or lose the benefits we gained.

-- StephenMarney, 24-Apr-98


After seeing what the restrictions proposed for putting "JOS" at the start of a class name, I am leaning towards yes for those very limited purposes only. However, I am still voting NO for what most of you will consider to be a tangential discussion not directly applicable to the topic at hand, but will be affected by the outcome of this vote.

If we say 'yes' to putting "JOS" at the start of every exposed interface, then we have effectively approved the notion that JOS should have exposed interfaces. It is my position that the only place where these 'exposed' interfaces should be used is in the implementation of the JavaPlatform itself, (i.e. java., and javax.) and the implementation of JOS specific code which we distribute. (And a further limitation being that the only code we write which uses such exposed interfaces will either not have a user interface, or would specifically be for the purpose of exposing a part of the OS as a system utility (such as a CodeRepositoryViewer, which would need access to the CodeRepository interfaces)). The thing I want to be careful of is that applications meant to be run on any implementation of the JavaPlatform not use these exposed JOS interfaces.

In short, I can agree with "JOS" being prefixed to exposed interfaces, only so long as the things which these interfaces are exposed to meet the above criteria. I would further add, however, that our code which uses the exposed interfaces in this manner is going to, by nature, use so much of our internal classes that "JOS" is going to need to be prefixed to most of the classes that we write.

So, my vote is still NO until the above conditions are met and my fear of "JOS" being prefixed to everything we write is allayed. Of course, with the vote very much in favor of yes, I doubt that is much of a roadblock. :)

-- AveryRegier 25-Apr-98


Stephen, there is a set of (pretty precise) rules that Jos... interfaces must conform to: see StefansAPIStructureProposal. Is this what you meant or am I getting you wrong?

Avery, sometimes we MUST define our own interface to applications. There is so much missing in java.. One example is the JosScout (a regular JOS application) that needs to "listen" to the file system, that is, get notified when files are created, moved etc. Such a feature is not present in java.. So we have to create a new interface.

Then, where put it? We have two possibilities: javax.* (an interesting idea; who controls/owns javax.? Is it free?) or org.jos.api..

I don't agree that most of the classes belonging to JOS will carry the prefix. I think it will be less than, say, 10% or even 5%. The idea is to keep the API lean. The "workhorse" classes are not public.

Does this meet the requirements for your "NO->YES" conversion, Avery? ;-)

--StefanReich, 26-Apr-98


it is redundent, not nessessay and bulky

WeoLopez


I won't repeat all the arguments, but for clarity's sake, YES.

DanielHarris


I propose placing all interfaces as static inner interfaces in a single abstract class like the following:
package org.jos.api; public abstract class JOS { public static interface APIRegistry { ... } ... }
In this scheme, there are three ways to name an interface: 1. the full name:
class XXX implements org.jos.api.JOS.APIRegistry
2. via the containing class:
import org.jos.api.JOS; class XXX implements JOS.APIRegistry
3. import the containing class:
import org.jos.api.JOS.*; class XXX implements APIRegistry
This gives you the flexibility of show the prefix if you want to clarify your code and hide it if the context is clear. The only down side is that all interfaces are defined in the same file. Fortunately this file will not be changed often.

What do you think?

-- LincolnCheung , 7 May 98


I say NO! That is what packages are for. Ever seen something like sun.SUNfoo?

-- BorkoJandras, 07-May-98


I'm probably late, but I vote a resounding NO. As has been pointed out, using proper, descriptive names for classes and packaging classes properly does everything necessary. Adding "Jos" to the front doesn't add anything except typing.

-- MichaelRichter , 3-June-98


It's maybe late but I say YES, because I think that's a good way to distinguish interfaces and their implementations.

-- SebastianGolze 30-June98


Methinks there is a bit of confusion. The question is not whether to prefix all JOS classfile names with JOS but to use this flag to indicate a part of the API, as compliant with it's versioning tricks. For that, I vote YES. Then again, maybe the confusion is all mine. --BenKnowles 16 July 98
I vote YES for the prefix. However i would like to raise a minor additional point. Since the Java language is case sensitive there's a difference between the "JOS" and the "Jos" prefix. People on this page seem to have used both interchangeably.
I would prefer to have the "JOS" prefix (standing for Java Operating System or whatever) than "Jos" (it reminds me too much of Jos Verstappen ;-). --RanieriArgentini September 18, 1998
No. I struggled with the very thing in my own work, and have found no point to it. jos classes already have their own packages, and don't need to be prefixed. One point was name conflicts. On the small chance that a conflick occures, an explicit reference can be used.

e.g. orj.jos.Registry com.jmonkey.Registry

So, if we must use a prefix, lets keep it short and sweet and use it sparingly. i.e. Sun used Jname for Swing... however this is a case where it was a good idea, because it is likely you would be mixing AWT and SWING components.

-- BrillPappin 16-Jan-1999


Content of these pages are owned and copyrighted by the poster.
Hosted by: