Method naming convention required

Discussion in 'Java' started by Xagyg, Oct 20, 2006.

  1. Xagyg

    Xagyg Guest

    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, Oct 20, 2006
    #1
    1. Advertising

  2. Xagyg

    Xagyg Guest


    >
    > 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.
     
    Xagyg, Oct 20, 2006
    #2
    1. Advertising

  3. Xagyg

    Daniel Dyer Guest

    On Fri, 20 Oct 2006 05:45:37 +0100, Xagyg <> wrote:

    >> 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.


    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.

    --
    Daniel Dyer
    http://www.dandyer.co.uk
     
    Daniel Dyer, Oct 20, 2006
    #3
  4. Xagyg wrote:
    > 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
    --
    The comp.lang.java.gui FAQ:
    http://gd.tuwien.ac.at/faqs/faqs-hierarchy/comp/comp.lang.java.gui/
    ftp://ftp.cs.uu.nl/pub/NEWS.ANSWERS/computer-lang/java/gui/faq
     
    Thomas Weidenfeller, Oct 20, 2006
    #4
  5. Xagyg

    Xagyg Guest

    Thomas Weidenfeller wrote:

    > 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.
     
    Xagyg, Oct 20, 2006
    #5
  6. Xagyg

    Chris Uppal Guest

    Xagyg wrote:

    > 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
     
    Chris Uppal, Oct 20, 2006
    #6
  7. Xagyg

    Xagyg Guest

    Chris Uppal wrote:

    > Xagyg wrote:
    >
    > > 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


    Nice post. Thanks. I'll work with something along these lines.
     
    Xagyg, Oct 20, 2006
    #7
  8. Xagyg wrote:
    > 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
     
    Thomas Hawtin, Oct 20, 2006
    #8
  9. Xagyg

    Doug Pardee Guest

    Xagyg wrote:
    > 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.)
     
    Doug Pardee, Oct 20, 2006
    #9
  10. Xagyg

    Mark Rafn Guest

    Thomas Hawtin <> wrote:
    >> 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?


    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.
    --
    Mark Rafn <http://www.dagon.net/>
     
    Mark Rafn, Oct 20, 2006
    #10
  11. Xagyg

    Stefan Ram Guest

    (Mark Rafn) writes:
    >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
     
    Stefan Ram, Oct 20, 2006
    #11
  12. 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
     
    Patricia Shanahan, Oct 20, 2006
    #12
  13. Xagyg

    djthomp Guest

    On Oct 20, 6:31 am, "Xagyg" <> wrote:
    > 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.
     
    djthomp, Oct 20, 2006
    #13
  14. Xagyg

    Mark Rafn Guest

    Stefan Ram <-berlin.de> wrote:
    > 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.
    --
    Mark Rafn <http://www.dagon.net/>
     
    Mark Rafn, Oct 21, 2006
    #14
  15. Xagyg

    Stefan Ram Guest

    (Mark Rafn) writes:
    >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.
     
    Stefan Ram, Oct 21, 2006
    #15
  16. Xagyg

    Mark Rafn Guest

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


    Stefan Ram <-berlin.de> wrote:
    > (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().
    --
    Mark Rafn <http://www.dagon.net/>
     
    Mark Rafn, Oct 21, 2006
    #16
  17. Daniel Dyer wrote:
    > On Fri, 20 Oct 2006 05:45:37 +0100, Xagyg <> wrote:
    >
    >>> 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.

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


    It's a Rubyism.

    --
    John W. Kennedy
    "The blind rulers of Logres
    Nourished the land on a fallacy of rational virtue."
    -- Charles Williams. "Taliessin through Logres: Prelude"
     
    John W. Kennedy, Oct 22, 2006
    #17
  18. Xagyg

    Chris Uppal Guest

    Stefan Ram wrote:
    > (Mark Rafn) writes:
    > > 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.


    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
     
    Chris Uppal, Oct 22, 2006
    #18
  19. Xagyg

    Xagyg Guest

    > 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.
     
    Xagyg, Oct 22, 2006
    #19
  20. Xagyg

    Godspeed Guest

    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.

    "Doug Pardee" <> wrote in message
    news:...
    > Xagyg wrote:
    >> 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.)
    >
     
    Godspeed, Oct 22, 2006
    #20
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Rick

    Which c# naming convention?

    Rick, Jan 19, 2004, in forum: ASP .Net
    Replies:
    1
    Views:
    3,846
    Paul Glavich
    Jan 19, 2004
  2. dm1608
    Replies:
    6
    Views:
    8,622
  3. Buck Turgidson

    JSP Method Naming Convention

    Buck Turgidson, Mar 2, 2004, in forum: Java
    Replies:
    1
    Views:
    1,791
    P.Hill
    Mar 2, 2004
  4. harry
    Replies:
    2
    Views:
    1,234
    harry
    Dec 8, 2004
  5. Roedy Green

    Naming Convention(s)

    Roedy Green, Sep 3, 2005, in forum: Java
    Replies:
    24
    Views:
    994
    Dale King
    Sep 12, 2005
Loading...

Share This Page