Method naming convention required

[Xagyg]

In Ruby, a method that modifies the instance using it is suffixed with
a '!'.

E.g. someString.reverse() returns a String with a reversed result,
however, someString.reverse! reverses the result of someString.

Does anyone have/use/know of a method-naming convention in Java to
distinguish between methods that modify the instance and methods that
don't?

Feel free to suggest one if you like.

 

[Xagyg]

E.g. someString.reverse() returns a String with a reversed result,
however, someString.reverse! reverses the result of someString.

reverses the result of someString.

I meant "reverses someString" in-place.

 

[Daniel Dyer]

I meant "reverses someString" in-place.

I'm not aware of any naming convention like this in Java. However, if you
are only concerned with Strings, it's impossible(*) to reverse them in
place anyway since they are immutable.

[*] Almost.

Dan.

 

[Thomas Weidenfeller]

Does anyone have/use/know of a method-naming convention in Java to
distinguish between methods that modify the instance and methods that
don't?

The attribute setter/getter convention taken from the JavaBeans spec
http://java.sun.com/j2se/1.5.0/docs/guide/beans/index.html is probably
closest:

void setSomething(type value)
type getSomething()

That convention is largely observed, even for non-JavaBean-compliant
classes. One can argue it is even often overused.

Other stuff is defined chapter 10 of

http://java.sun.com/docs/codeconv/index.html

/Thomas

 

[Xagyg]

The attribute setter/getter convention taken from the JavaBeans spec
http://java.sun.com/j2se/1.5.0/docs/guide/beans/index.html is probably
closest:

void setSomething(type value)
type getSomething()

That convention is largely observed, even for non-JavaBean-compliant
classes. One can argue it is even often overused.

I'll give another example. I want my Set class to have 2 "union"
methods. The first method unions another set to the caller. The second
one unions another set and returns a new set, but the caller is not
modified.

e.g. this.union(s) modifies this, whereas the other version of
this.union(s) does NOT modify this, it returns a new set containing the
union of this and s. It might seem a little strange to have setUnion(s)
and getUnion(s) since the set and get are actually doing extra
processing ... not just setting and getting some object. I like the
suggestion though - it is based on a sound principle. Not sure it feels
right though.

 

[Chris Uppal]

I'll give another example. I want my Set class to have 2 "union"
methods. The first method unions another set to the caller. The second
one unions another set and returns a new set, but the caller is not
modified.

Call the second union(), but don't call the first one that, since that's not
what "union" means. If it fits with your framework then use the established
name addAll() instead.

(addAll() is part of the contract defined by the java.util.Collection
interface.)

A more general point: I think that one good way to distinguish between methods
which modify the target object and those which answer a modified version is to
(try to) follow the English pattern: verb/verbed. So that the string reversal
example would have methods called reverse() (which modified the string in
place), and reversed() which returned a reversed copy. Of course you can go
beyond that into, say, beReversed() vs reversed(), or even reverse() vs
copyReversed().

It's a bit unfortunate that there isn't a Lisp/Ruby style qualifier character
available, but there isn't. And also there is no established convention, so we
just have to do the best we can with well chosen method names (fighting the
oddities of English grammar the while...)

-- chris

 

[Xagyg]

Call the second union(), but don't call the first one that, since that's not
what "union" means. If it fits with your framework then use the established
name addAll() instead.

(addAll() is part of the contract defined by the java.util.Collection
interface.)

A more general point: I think that one good way to distinguish between methods
which modify the target object and those which answer a modified version is to
(try to) follow the English pattern: verb/verbed. So that the string reversal
example would have methods called reverse() (which modified the string in
place), and reversed() which returned a reversed copy. Of course you can go
beyond that into, say, beReversed() vs reversed(), or even reverse() vs
copyReversed().

It's a bit unfortunate that there isn't a Lisp/Ruby style qualifier character
available, but there isn't. And also there is no established convention, so we
just have to do the best we can with well chosen method names (fighting the
oddities of English grammar the while...)

-- chris

Nice post. Thanks. I'll work with something along these lines.

 

[Thomas Hawtin]

In Ruby, a method that modifies the instance using it is suffixed with
a '!'.

E.g. someString.reverse() returns a String with a reversed result,
however, someString.reverse! reverses the result of someString.

Does anyone have/use/know of a method-naming convention in Java to
distinguish between methods that modify the instance and methods that
don't?

The convention is that mutable objects stick with methods that mutate
themselves. Equivalent methods return results without modifying the
source objects belong to immutables.

Tom Hawtin

 

[Doug Pardee]

Does anyone have/use/know of a method-naming convention in Java to
distinguish between methods that modify the instance and methods that
don't?

Not a naming convention, but a signature convention:
If the method has a return value, it doesn't modify anything.
If the method modifies anything, it doesn't have a return value.

This is called Command/Query Separation. CQS is generally considered to
be a good thing to do, although there are a few isolated instances
where there is real value in returning a value from a method that
modifies things.

Virtually all programming languages prior to C strictly separated
statements from expressions, subroutines from functions. C introduced
side-effect functions, statement expressions, and expression
statements, and derivative languages like Java have followed suit. But
just because a language allows you to do something and doing so saves
you ten keystrokes, that doesn't mean that it's a good idea in terms of
code quality.

(Most languages couldn't actually stop you from putting a side effect
into a function definition, but it wasn't something that was routinely
done, particularly if there was a chance that the compiler might
optimize the function calls.)

 

[Mark Rafn]

How I wish the language supported this! There's probably no reason not to add
an annotation (@Const is probably too controversial, but @ReadOnly could work)
to indicate methods that don't change any values.

The convention is that mutable objects stick with methods that mutate
themselves. Equivalent methods return results without modifying the
source objects belong to immutables.

Note that this convention is not universal, even within the JDK.
StringBuilder, for instance, mutates and returns a copy itself for easy
chaining of calls.

It's a good idea to follow it when you can, but there's no subsitute for
understanding the API you're calling and knowing which methods read vs write.

 

[Stefan Ram]

How I wish the language supported this! There's probably no
reason not to add an annotation (@Const is probably too
controversial, but @ReadOnly could work) to indicate methods
that don't change any values.

Support for this might be found to some extend in libraries,
when the "value" (immutable) or "state system" (mutable)
nature of objects is documented.

In my library, I have two package prefixes

de.dclj.ram.system...

packages with this prefix contain classes, whose
instances model systems (i.e., mutable state systems).

de.dclj.ram.type....

packages with this prefix contain classes, whose
instances model values (i.e., immutable values).

http://www.purl.org/stefan_ram/html/ram.jar/overview-frame.html

 

[Patricia Shanahan]

Doug Pardee wrote:
....

Virtually all programming languages prior to C strictly separated
statements from expressions, subroutines from functions. C introduced
side-effect functions ...

Is a Fortran function that modifies a common block a side-effect function?

Patricia

 

[djthomp]

e.g. this.union(s) modifies this, whereas the other version of
this.union(s) does NOT modify this, it returns a new set containing the
union of this and s. It might seem a little strange to have setUnion(s)
and getUnion(s) since the set and get are actually doing extra
processing ... not just setting and getting some object. I like the
suggestion though - it is based on a sound principle. Not sure it feels
right though.

One approach would be to use static class methods for all of the
functions that produce new objects.

i.e. Set.union(setA, setB)

Just a thought.

 

[Mark Rafn]

Support for this might be found to some extend in libraries,
when the "value" (immutable) or "state system" (mutable)
nature of objects is documented.

Sure, I like immutable value objects when possible. Documenting this is
fairly painless, and I haven't seen much need for conventions around it. The
OP was asking about (and I agree with) how to determine which methods on a
mutable object actually change the state.

 

[Stefan Ram]

The OP was asking about (and I agree with) how to determine
which methods on a mutable object actually change the state.

This might be considered to be an implementation detail,
which should not be visible to a client.

Why should a client programmer need to know this?

For example,

shape.rotate( a )

might rotate a shape around its center (of gravity) by the
angle a.

After

Shape shape = new Rectangle();

"rotate" will change the state, while after

Shape shape = new Circle();

"rotate" might be a no-operation (not changing the state of
its object). So "rotate" in the interface "Shape" can not be
named to reflect both a state change and no state change.

Moreover, for certain values of a, like "0" or multiples of
360 degrees, "rotate( a )" may not change the state of a
rectangle.

Or, when a method does not change the state of its object, but
the state of a referenced object, should this considered to be
a change of the state of the object, too?

Does

System.out.println( "a" );

change the state of the object "System.out"? If this is
take to represent the console, the answer is "yes", because
text is added to the console. However, the answer might
be "no", if only the modification of primitve fields are
considered to be a change.

 

[Mark Rafn]

The OP was asking about (and I agree with) how to determine

(e-mail address removed) (Mark Rafn) writes:
This might be considered to be an implementation detail,
which should not be visible to a client.

Not at all, it's a critical part of an API to know when an object will mutate.

shape.rotate( a )
might rotate a shape around its center (of gravity) by the
angle a.

Knowing whether this returns a new Shape that is rotated or whether it mutates
the given Shape is fairly important to the caller.

Shape shape = new Rectangle();
"rotate" will change the state, while after
Shape shape = new Circle();
"rotate" might be a no-operation (not changing the state of

Sure, but who cares? A mutator that happens not to need to do anything is
harmless. It's the opposite that causes bugs: a method the caller thinks is
non-state-changing but actually mutates.

its object). So "rotate" in the interface "Shape" can not be
named to reflect both a state change and no state change.

It is a state-changing method, clearly. Unless it is really a clone+rotate
method that returns a new object.

Does System.out.println( "a" ); change the state of the object "System.out"?

Funny edge case, but easy to answer: no. There's nothing that System.out will
do differently after calling println().

 

[John W. Kennedy]

I'm not aware of any naming convention like this in Java.

It's a Rubyism.

 

[Chris Uppal]

This might be considered to be an implementation detail,
which should not be visible to a client.

I have claimed before that "state" is not really something that belongs to an
object in an OO system. That's to say that it's not an observable property of
any object considered in isolation, but only of the system (or subsystem) as a
whole.

So, although whether a given method changes the observable state of the system
(or /might/ do so) is very definitely not an implementation detail, whether it
changes the internal state of the receiving object itself /is/ an
implementation detail.

So I would say that there's nothing at all wrong with wanting to indicate what
a method does by proper choice of its name -- hell, that's what method names
are /for/ ! -- but that the notion of "change" is subtle and should not be
interpreted naively.

Note, btw, that whether a method is a mutator (in the above OO sense) is a
property of a cluster of polymorphically interchangeable concrete methods. If
only Circles have rotate() then there's something insane in the design; if
rotate() is a method common to several shapes, then rotate() is a mutator even
if the implementation in Circle happens to be a no-op.

-- chris

 

[Xagyg]

One approach would be to use static class methods for all of the

functions that produce new objects.

i.e. Set.union(setA, setB)

This is a reasonable approach and was my first thought. However, it
makes chaining calls less obvious.

For example --

we want: r.domRes(tomSet).union(q).rangeRes(carSet).contains(?)

Using statics produces ugly chaining which is not the natural order of
our query. Nice chaining requires use of object instances.

Ugly chaining (using statics):


assertTrue(Relation.rangeRestriction((Relation)Relation.domainRestriction(r,new
Set("tom")).union(q),new Set("car")).contains(new
Maplet("jane","car")));

Nice chaining:

assertTrue(((Relation)r.domainRestriction(new
Set("tom")).union(q)).rangeRestriction(new Set("car")).contains(new
Maplet("jane","car")));

Now, I have domainRestriction which returns a new object (i.e. no
update to caller). And I have domainRestrict which updates the caller.
Statics would allow naming them the same (since the signatures are
different), but see problem immediately above.

I am thinking of using: domainRestriction for the no-update call, and
something like restrictByDomain for the update call. Currently I have
domainRestriction and domainRestrict which is probably too close.

If anyone is interested at looking further into the project, see
http://sourceforge.net/projects/zedlib

Thanks for all the comments and ideas.

 

[Godspeed]

This approach wouldn't be so bad except for the case where the only
difference between the methods is their return value. As you know, Java does
not allow methods whose only diff is their return value.

Also, loads of Java classes return a value for modifying methods (e.g.
Set.add returns true/false if the set was changed due to the operation)...
however, I like your general idea/approach.