Terminolgy: the verb corresponding to "toString"

Discussion in 'Java' started by Roedy Green, Jul 31, 2008.

  1. Roedy Green

    Roedy Green Guest

    What is the tersest way to document a toString style method.

    I would like to say something like this:

    "displays" the width and height in both metric and imperial measure

    But it does not display anything, just prepares for display.

    I have seen people also use misleading terms like "show" and "print".

    What do you use?

    The best I can come up with is "format". Sun uses this is the
    SimpleDateFormat class.

    To me, "format" implies some sort of complicated masks or a choice of
    layouts.

    "prepare" is too vague.

    Perhaps a phase "convert x to a string"

    --

    Roedy Green Canadian Mind Products
    The Java Glossary
    http://mindprod.com
     
    Roedy Green, Jul 31, 2008
    #1
    1. Advertising

  2. Roedy Green

    Nigel Wade Guest

    Roedy Green wrote:

    > What is the tersest way to document a toString style method.
    >
    > I would like to say something like this:
    >
    > "displays" the width and height in both metric and imperial measure
    >
    > But it does not display anything, just prepares for display.
    >
    > I have seen people also use misleading terms like "show" and "print".
    >
    > What do you use?
    >
    > The best I can come up with is "format". Sun uses this is the
    > SimpleDateFormat class.
    >
    > To me, "format" implies some sort of complicated masks or a choice of
    > layouts.
    >
    > "prepare" is too vague.
    >
    > Perhaps a phase "convert x to a string"
    >


    Is there anything wrong with what Object.toString() says?

    "Returns a string representation of the object. "
    ...
    "The toString method for class Object returns a string consisting of..."

    Seems to do pretty much cover it.

    --
    Nigel Wade
     
    Nigel Wade, Jul 31, 2008
    #2
    1. Advertising

  3. Roedy Green

    Tom Anderson Guest

    On Thu, 31 Jul 2008, Eric Sosman wrote:

    > Roedy Green wrote:
    >
    >> Perhaps a phase "convert x to a string"

    >
    > I've seen "stringize" used as a verb, but I don't like it much.
    > Besides, speakers of Q.E. will want to spell it "stringise" and there'll
    > be no end of fruitless debatez.


    I've come across 'stringify', which i think is much better than
    'stringize', but still probably unnecessary jargon.

    tom

    --
    roger and kay payne, symmetry, piercing, archaeology, position, in ,,
     
    Tom Anderson, Jul 31, 2008
    #3
  4. Roedy Green wrote:
    > What is the tersest way to document a toString style method.
    >
    > I would like to say something like this:
    >
    > "displays" the width and height in both metric and imperial measure
    >
    > But it does not display anything, just prepares for display.
    >
    > I have seen people also use misleading terms like "show" and "print".
    >
    > What do you use?
    >
    > The best I can come up with is "format". Sun uses this is the
    > SimpleDateFormat class.
    >
    > To me, "format" implies some sort of complicated masks or a choice of
    > layouts.
    >
    > "prepare" is too vague.
    >
    > Perhaps a phase "convert x to a string"
    >


    "Returns a String describing ..."
    "Returns a description of ..."
    "Describes ..."

    --
    RGB
     
    RedGrittyBrick, Jul 31, 2008
    #4
  5. Roedy Green

    Daniel Pitts Guest

    Roedy Green wrote:
    > What is the tersest way to document a toString style method.
    >
    > I would like to say something like this:
    >
    > "displays" the width and height in both metric and imperial measure
    >
    > But it does not display anything, just prepares for display.
    >
    > I have seen people also use misleading terms like "show" and "print".
    >
    > What do you use?
    >
    > The best I can come up with is "format". Sun uses this is the
    > SimpleDateFormat class.
    >
    > To me, "format" implies some sort of complicated masks or a choice of
    > layouts.
    >
    > "prepare" is too vague.
    >
    > Perhaps a phase "convert x to a string"
    >

    /**
    * Returns a String representation of this object.
    * ${detailsOfStringFormatIfApplicable}
    * ${warningAboutDetailsChangingInFutureIfApplicable}
    * @returns a String suitable for (debugging, parsing, sending, etc...)
    */

    --
    Daniel Pitts' Tech Blog: <http://virtualinfinity.net/wordpress/>
     
    Daniel Pitts, Jul 31, 2008
    #5
  6. Roedy Green

    Stefan Ram Guest

    Roedy Green <> writes:
    >"displays" the width and height in both metric and imperial measure


    »o.toString()« "designates", "denotes", "gives",
    "expresses" a string, or "evaluates to" a string.

    (I do not use »returns« here, because an expression does not
    »return« its value. »2« does not »return« 2, it designates 2.
    I use »return« only when I want to take the point of view of
    the /implementation/ of a method. It is the view from /inside/
    a method that can use »return«.)
     
    Stefan Ram, Jul 31, 2008
    #6
  7. Roedy Green

    Roedy Green Guest

    On Thu, 31 Jul 2008 13:29:51 +0200, Andrea Francia
    <èdatogliereohohoho.it> wrote, quoted
    or indirectly quoted someone who said :

    >The verb is "Returns a string"


    It is a little verbose.

    You can't use it as a verb in other contexts. e.g.

    // convert the co-ordinates to String format for display.

    It would be nice to abbreviate that to something like

    // format the co-ordinates
    // express the co-ordinates
    // present the co-ordinates
    // exhibit the co-ordinates
    // render the co-ordinates
    // flatten the co-ordinates

    It might be best to pick a fairly obscure word that has no attendant
    ambiguous meanings.

    Two related problems:

    1. What if you have several toString-style methods. e.g.
    toISODateSTring toLocalisedDateString. Should those be called
    formatISODate or formatAsISODate? I am a stickler for consistency.


    2. How do you do the Javadoc to avoid redundancy
    and potential inconsistency. e.g.

    /** returns date converted to an ISO date String of the form
    YYYY-MM-DD in local time.
    @param theDate date you want to display.
    @return the date converted to an ISO date String of the form
    YYYY-MM-DD
    */

    --

    Roedy Green Canadian Mind Products
    The Java Glossary
    http://mindprod.com
     
    Roedy Green, Jul 31, 2008
    #7
  8. Roedy Green

    Stefan Ram Guest

    Roedy Green <> writes:
    >2. How do you do the Javadoc to avoid redundancy
    >and potential inconsistency. e.g.
    >/** returns date converted to an ISO date String of the form
    >YYYY-MM-DD in local time.
    >@param theDate date you want to display.
    >@return the date converted to an ISO date String of the form
    >YYYY-MM-DD
    >*/


    The repetition of »date converted to an ISO date String of the
    form YYYY-MM-DD« in this case is endorsed by the style guidelines:

    »The @return tag is required for every method that returns
    something other than void, even if it is redundant with
    the method description. (Whenever possible, find something
    non-redundant (ideally, more specific) to use for the tag
    comment.)«

    http://java.sun.com/j2se/javadoc/writingdoccomments/

    Inconsistency is avoided by attention of the author/editor,
    a cut-and-paste-habbit, or a preprocessor:

    $define VALUE the date converted to an ISO date String
    /** Returns $VALUE.
    @param theDate date to display
    @return $VALUE */

    There should not be a period after »date you want to display«:

    »End the phrase with a period only if another phrase or
    sentence follows it.

    Example:

    * @param ch the character to be tested«

    http://java.sun.com/j2se/javadoc/writingdoccomments/

    All the documentation comments for methods in this source
    »writingdoccomments« start with upper case letters.
    So it should probably be »/** Returns« (not »/** returns«).
     
    Stefan Ram, Jul 31, 2008
    #8
  9. Roedy Green

    Mark Space Guest

    Roedy Green wrote:
    > What is the tersest way to document a toString style method.
    >
    > I would like to say something like this:
    >
    > "displays" the width and height in both metric and imperial measure
    >
    > But it does not display anything, just prepares for display.
    >
    > I have seen people also use misleading terms like "show" and "print".


    stream (as in stream to disc)

    write (as in write to a printer)

    encode (as in to a specific character set)

    getString, getAsString

    enstring (like enclose or encapsulate)

    render (I think this got mentioned)

    Serialize ... don't forget you can write objects to an internal buffer
    using StringWriter... maybe you should be using the API more rather than
    rolling your own methods. Make a print( OutputStream o ) method, then
    just hand it a StringWriter if you don't really want it to go anywhere.
     
    Mark Space, Aug 1, 2008
    #9
  10. Roedy Green

    Mark Space Guest

    Andrea Francia wrote:

    >
    > How do you would write a Javadoc comment for a method like that?
    >
    > How do you write the Javadoc comments for the setter and the getter
    > methods?


    I think Lew is saying there is no formula or specification. It's an ad
    hoc process, part black art. Toward that end, here's some example from
    Sun's Java docs:

    getColumns

    public int getColumns()

    Returns the number of columns in this TextField.

    Returns:
    the number of columns >= 0


    ((It's important to remember that the first sentence will appear in the
    summary at the top of a class's Java doc page.))


    getColumnWidth

    protected int getColumnWidth()

    Returns the column width. The meaning of what a column is can be
    considered a fairly weak notion for some fonts. This method is used to
    define the width of a column. By default this is defined to be the width
    of the character m for the font used. This method can be redefined to be
    some alternative amount

    Returns:
    the column width >= 1


    getPreferredSize

    public Dimension getPreferredSize()

    Returns the preferred size Dimensions needed for this TextField. If
    a non-zero number of columns has been set, the width is set to the
    columns multiplied by the column width.

    Overrides:
    getPreferredSize in class JComponent

    Returns:
    the dimension of this textfield
    See Also:
    JComponent.setPreferredSize(java.awt.Dimension), ComponentUI


    ((Notice that the main text portion tends to be in a more
    conversational, informal style, whereas the @Returns portion attempts to
    set some formal invariants on the return type. Notice also that the
    last quote above seems to break this by not really saying anything about
    the range of the Dimension object returned. Possibly this is because
    describing the range of return values for a Dimension would be verbose,
    and Sun feels the @Return comment should be brief.))


    setColumns

    public void setColumns(int columns)

    Sets the number of columns in this TextField, and then invalidate
    the layout.

    Parameters:
    columns - the number of columns >= 0
    Throws:
    IllegalArgumentException - if columns is less than 0


    ((Notice here how the return invariant of getColumns, and the parameter
    required invariant match up with setColumns.))


    getColumnWidth

    protected int getColumnWidth()

    Returns the column width. The meaning of what a column is can be
    considered a fairly weak notion for some fonts. This method is used to
    define the width of a column. By default this is defined to be the width
    of the character m for the font used. This method can be redefined to be
    some alternative amount

    Returns:
    the column width >= 1


    ((There is no setPreferredSize method for this class, it inherits from
    JComponent.))


    setPreferredSize

    public void setPreferredSize(Dimension preferredSize)

    Sets the preferred size of this component. If preferredSize is
    null, the UI will be asked for the preferred size.

    Overrides:
    setPreferredSize in class Component

    Parameters:
    preferredSize - The new preferred size, or null
    See Also:
    Component.getPreferredSize(), Component.isPreferredSizeSet()


    ((Possibly the specified interaction with the rest of the UI is why they
    don't specify much about the invariants on a Dimension return from
    getPreferredSize -- it's out of the hands of the writer of the Java doc
    for this class.))
     
    Mark Space, Aug 1, 2008
    #10
  11. Roedy Green

    Lew Guest

    Barbara Gregorie wrote:
    > I think this would fit the java style better than the use of casting,
    > which just betrays its C ancestry.


    Cast or proficiency call - hmmm. Seems like either way it's inconsistent to be incorrect.
    Whether one is "better" than the other seems like conceding whether conditional
    spectacle is better than milk pepper.

    "Just concurs its C elitist" - hmmm. There's a condemnation! Don't paralyze Java
    - it embraces its C astrologer!

    You've enacted me!

    --
    Lew


    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    "How can we return the occupied territories?
    There is nobody to return them to."

    --- Golda Meir,
    March 8, 1969.
     
    Lew, Aug 2, 2008
    #11
  12. Roedy Green

    Roedy Green Guest

    On Fri, 01 Aug 2008 08:39:20 -0400, Lew <com.lewscanon@lew> wrote,
    quoted or indirectly quoted someone who said :

    >
    >It still makes sense to *think* about the Javadoc, and not just take
    >boilerplate text. Laziness in the Javadoc phase is not a virtue.


    There is a general principle in programming that you should specify
    any given fact in only one place. If you specify it redundantly sooner
    or later someone (perhaps you) will forget to update one of the
    copies.

    I think this is what is behind my complaint with redundant wording in
    Javadoc.


    It is also behind my complaint with code of the form

    HashMap<String,ThingAMaJig> thingamajigs
    = new( HashMap<String,ThingAMaJig>( THINGAJIG_CAPACITY );

    The type of thingamajigs should be specified in only one place.
    It requires proofreading to make sure both sides stay identical.

    It is also behind my complaint with code of this form:

    Short s = (short)someFile.length();

    The fact that s is short should be specified in only one place.




    --

    Roedy Green Canadian Mind Products
    The Java Glossary
    http://mindprod.com
     
    Roedy Green, Aug 2, 2008
    #12
  13. On Sat, 02 Aug 2008 11:46:57 -0400, Lew wrote:

    > Which would cause trouble with narrowing conversions. The cast is not
    > redundant.
    >

    I've always liked the Algol 68 approach. You couldn't use casts to
    achieve narrowing or widening: indeed the language didn't allow them
    IIRC. Nothing was needed for widening because that can easily be made
    automatic (smallint to int or int to real) because this can't loose
    information: just pad with zeros, extend a sign or conceptually add '.0'
    for promotion of an int to a real. However, narrowing always required the
    programmer to specify what was to be discarded by using the approariate
    function: in converting a real to an int whether you want to round or
    truncate.

    I think this would fit the java style better than the use of casting,
    which just betrays its C ancestry.


    --
    martin@ | Martin Gregorie
    gregorie. | Essex, UK
    org |
     
    Martin Gregorie, Aug 2, 2008
    #13
    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. Kenneth Myhra

    HTTP error 405 for 'PUT' verb

    Kenneth Myhra, Feb 17, 2004, in forum: ASP .Net
    Replies:
    1
    Views:
    1,081
    bruce barker
    Feb 17, 2004
  2. =?Utf-8?B?UmV6YSBTb2xvdWtp?=

    The web serve has been locked down and is blocking the Debug verb.

    =?Utf-8?B?UmV6YSBTb2xvdWtp?=, Nov 24, 2004, in forum: ASP .Net
    Replies:
    3
    Views:
    3,615
    Ben Strackany
    Nov 24, 2004
  3. Randy
    Replies:
    0
    Views:
    436
    Randy
    Mar 29, 2006
  4. Fergus McMenemie

    LibXML element->toString vs document->toString

    Fergus McMenemie, Jul 12, 2012, in forum: Perl Misc
    Replies:
    5
    Views:
    624
    Fergus McMenemie
    Jul 17, 2012
  5. Rick Johnson

    PyWart (Terminolgy): "Class"

    Rick Johnson, Jan 14, 2013, in forum: Python
    Replies:
    15
    Views:
    228
    Steven D'Aprano
    Jan 15, 2013
Loading...

Share This Page