Terminolgy: the verb corresponding to "toString"

[Roedy Green]

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"

 

[Nigel Wade]

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.

 

[Tom Anderson]

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

 

[RedGrittyBrick]

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

 

[Daniel Pitts]

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...)
*/

 

[Stefan Ram]

"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«.)

 

[Roedy Green]

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
*/

 

[Stefan Ram]

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

 

[Mark Space]

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]

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

 

[Lew]

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.

 

[Roedy Green]

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.

 

[Martin Gregorie]

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.