[sip-comm-dev] utility classes


#1

Hello again Alex,

This is my last mail for today I promise :slight_smile:

While looking at Assert I noticed that you've been busy adding classes
in the util package. There's something we should keep in mind about that
package. Classes defined in there should be considered as an exclusive
global project convention and almost a MUST for every project developer.

Take the Logger for example. It is more than clear that a project needs
to use a single logging utility and hence the Logger class in the util
directory. Assert, should it has been accepted, would have made another
example for a globally exclusive utility (after all, its alternative is
a java keyword)

So given the weigth of utility packages, we should be careful not to
fill them with tools that are simply useful because that would draw
attention away from those that are actually project conventions.

Before deciding to add something in the util package, we should first be
convinced that people all over the project MUST use that tool and
nothing else.

We should then have these tools discussed, and approved by a majority of
developers who would from now on be aware that they would only use that
tool in case they need something with similar functionality.

Therefore, could you please remove EnumerationBase,
BidirectionalIterator and QuoteTokenizer away from util and into the
packages that actually use them.

Once you have done that, if you are convinced that there is a need
of imposing them as project conventions and that people shouldn't use
alternatives, you may start a discussion for everyone of them.

Cheers
Emil

路路路

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@sip-communicator.dev.java.net
For additional commands, e-mail: dev-help@sip-communicator.dev.java.net


#2

Hi everybody,

Hello again Alex,

This is my last mail for today I promise :slight_smile:

While looking at Assert I noticed that you've been
busy adding classes
in the util package. There's something we should
keep in mind about that
package. Classes defined in there should be
considered as an exclusive
global project convention and almost a MUST for
every project developer.

This is the most fundamental question I would like to
discuss. From my point of view a "utility" is
something "usefull". For me (I underline that this is
a personal oppinion) this is something like the Swiss
army knife. In one such package I would like to have
amost anything that would make my life easier.

There exists the problem with the size. There is a
dedicated bundle for the util package, so any class
added to this package will be distributed to all
systems. However has it's pros and cons. The advantage
is that once added a class can be used from all other
services - so it will save space. The negative side is
that on a given system the unused classes are a waste
of disk space. Nowadays when downloading a film from
the net is considered a piece of cake I don't think
that anyone would mind an extra 10-2000k (for the sake
of faster development). We should only take care with
the small devices with limited resources.

A possible solution to this problem is to have two
util packages. One with the stuff everyone uses (such
as Logger), and the other one with much broader
content. They both come with SIP Communicator, only
the second one may not be installed by default on
PDAs, etc.. This arrises other questions such as -
what should a developer do in order to be sure that
hers service would work "anywhere anytime". Well, she
would have to ship the classes from the "broad util"
along with her bundle, BUT at least she would not have
to write them every time. Or she may ship both her
bundle and the "broad util", or the dependency can be
managed by the SIP Communicator itself.

Another point is that we should probably add some
sub-packages to util, such as parsers, common, io,
net, etc...

In conclusion - I think that restricting the libraries
available to the programmer would slow down the
development of SIP Communicator. I'm not talking about
bloating the code. I'm talking about the case when we
wonder if we "really really need this code" or we only
"really need it".

Take the Logger for example. It is more than clear
that a project needs
to use a single logging utility and hence the Logger
class in the util
directory. Assert, should it has been accepted,
would have made another
example for a globally exclusive utility (after all,
its alternative is
a java keyword)

So given the weigth of utility packages, we should
be careful not to
fill them with tools that are simply useful because
that would draw
attention away from those that are actually project
conventions.

I agree that it is great to have such a package where
only the most fundamental classes reside. However I am
not convinced that we should sacrifice the entire
"util" package for this purpose. Actually here we may
be discussing a naming convention issue. For me those
classes belong to the "base", or "fundamental"
package.

Before deciding to add something in the util
package, we should first be
convinced that people all over the project MUST use
that tool and
nothing else.

We should then have these tools discussed, and
approved by a majority of
developers who would from now on be aware that they
would only use that
tool in case they need something with similar
functionality.

Therefore, could you please remove EnumerationBase,
BidirectionalIterator and QuoteTokenizer away from
util and into the
packages that actually use them.

This is a very good illustration of what I was talking
about. QuoteTokenizer was a usefull class for parsing
strings. Then I started using Jaxon and it became
"unused".. If it's place is not in the util package
then it should be deleted.. for ever. And when
tomorrow if someone needs it she will have to write it
again.

The same goes for the EnumerationBase. It tries to
emulate the "enum" keyword introduced with Java 1.5. I
used it heavily in two different services. Then I
simplified the API provided by those services and for
the moment this class is unused.

Once you have done that, if you are convinced that
there is a need
of imposing them as project conventions and that
people shouldn't use
alternatives, you may start a discussion for
everyone of them.

I've deleted the QuoteTokenizer (hope that I'll not be
needing it some day), also deleted EnumerationBase,
and moved BidirectionalIterator to the only service
that's using it for now.

Cheers
Emil

I don't have sufficient experience in designing
complex systems (especially open-source) and maybe I
am going against some well-known rule of a tumb. If
this is the case I appologise to everyone for the
wasted time :wink:

Regards,
Alex

路路路

--- Emil Ivov <emil_ivov@yahoo.com> wrote:

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@sip-communicator.dev.java.net
For additional commands, e-mail: dev-help@sip-communicator.dev.java.net


#3

<snip>

There's something we should
keep in mind about that
package. Classes defined in there should be
considered as an exclusive
global project convention and almost a MUST for
every project developer.

This is the most fundamental question I would like to
discuss. From my point of view a "utility" is
something "usefull". For me (I underline that this is
a personal oppinion) this is something like the Swiss
army knife. In one such package I would like to have
amost anything that would make my life easier.

A possible solution to this problem is to have two
util packages. One with the stuff everyone uses (such
as Logger), and the other one with much broader
content. They both come with SIP Communicator, only
the second one may not be installed by default on
PDAs, etc.. This arrises other questions such as -
what should a developer do in order to be sure that
hers service would work "anywhere anytime". Well, she
would have to ship the classes from the "broad util"
along with her bundle, BUT at least she would not have
to write them every time. Or she may ship both her
bundle and the "broad util", or the dependency can be
managed by the SIP Communicator itself.

I don't have sufficient experience in designing
complex systems (especially open-source) and maybe I
am going against some well-known rule of a tumb. If
this is the case I appologise to everyone for the
wasted time :wink:

If I recall accurately, the jakarta project hit this problem a couple of years ago. They had lived with it a long time before the pain forced them to change...

They created a package called "Commons" which contained almost-always-essential classes, such as their Logger. (I don't know whether they also have a "util" package for swiss army knives and other handy
tools).

and then it caused more pain.... because packaging changes always cause pain, e.g. breaking the build, breaking tests, forcing signature changes, etc.

.... but eventually things settled down and life because simpler....

until they started using their Commons package in several projects and it became a nightmare to manage the circular dependencies in the build....

... so they created a Commons Project at the root of the dependency tree.... more pain, but it is over now.

I vote for a "common" package for Emil, and let us suffer the pain quickly. Let Alex and the rest of us have a "util" package for stuff that feels generally useful, which we don't want to hide inside a specific package.
Regards,

Brian

路路路

On Wed, 30 Nov 2005 06:38:36 -0800 (PST), Alexander Pelov wrote:

--- Emil Ivov <emil_ivov@yahoo.com> wrote:

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@sip-communicator.dev.java.net
For additional commands, e-mail: dev-help@sip-communicator.dev.java.net


#4

Hi Alex and all developers,

Alexander Pelov wrote:

I don't have sufficient experience in designing
complex systems (especially open-source) and maybe I
am going against some well-known rule of a tumb. If
this is the case I appologise to everyone for the
wasted time :wink:

This example perfectly show us how important it is to have a clear and complete guideline that *every* developer must follow in order to avoid such kind of situation.

I think this is a good occasion to define a guideline concerning changes in SC base architecture and utility classes :slight_smile:

Before committing a new utility class, we need to ask ourselves few questions:

* is this class really needed in the common part of SC? Ok it is requiered for my service (otherwhise I wouln't have written it), but how to be sure it's good for the whole project?

* is this class useful for everybody the way I see it? My needs may differ from another developer's ones and thus committing a class without this certitude may hamper his work when he wants to use it.

The only way to get sure of these is to start a discussion on the dev mailing list and waiting to have feedback. Of course, other developers are asked to give their feelings about such a class or a change in the architecture.

I agree with Emil when he says that we should be careful when adding code to common project parts: bypassing these precaution steps could really hurt the project.

WDYT?

Martin


#5

Martin Andr锟 wrote:

I think this is a good occasion to define a guideline concerning changes in SC base architecture and utility classes :slight_smile:

Point taken! I'll get on to that.

Thanks Martin
Emil

路路路

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@sip-communicator.dev.java.net
For additional commands, e-mail: dev-help@sip-communicator.dev.java.net


#6

I agree with Emil when he says that we should be careful when adding
code to common project parts: bypassing these precaution steps could
really hurt the project.

Some time ago I decided to drop Java from my development toolkit. The
main reason was that while being a decent language, the culture within
the community more often than not leads to over-design and
over-engineering. Mind you, I don't want to start a flame war :slight_smile:

Why I'm saying that? Well, from past experience, I've found it is good
to be realtively conservative in what to accept as part of a common
base/package/bundle. The yardstick usually was - is the utility actually
used by enough packages to merit the move, or is there enough support
for a utility to move to a common/core package. Before that - no. Stay
where you are.

That said "it is a good thing"tm, to have the infrastructure to enable
the move. Whether it is called common, utility, SAK, doesn't really
matter.

What I'm trying to say in two words is, I wouldn't try to complicate
things early on.

At some point, if it is decided for something to change it's name,
because it is very useful, it can be done not too painfully.
Generally it is an awk/sed job. You can always use a temporary
place-holder for the old name, informing that the utitly was
deprecated, and has moved.

Though my 2 cents could be useful.

Vlado

路路路

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@sip-communicator.dev.java.net
For additional commands, e-mail: dev-help@sip-communicator.dev.java.net