Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.java.programmer > #30042 > unrolled thread

class member object of many uses "this"

Back to article view | Back to comp.lang.java.programmer

Contents

  class member object of many uses "this" c123456749@gmail.com - 2014-09-30 13:38 -0700
    Re: class member object of many uses "this" Eric Sosman <esosman@comcast-dot-net.invalid> - 2014-09-30 17:26 -0400
      Re: class member object of many uses "this" Eric Sosman <esosman@comcast-dot-net.invalid> - 2014-09-30 17:30 -0400

#30042 — class member object of many uses "this"

In documentation, what terminology should I use when I refer to the "this" object. Specifically, I have a class member that uses "this". And, I want to write clear documentation.

Thanks,

[toc] | [next] | [standalone]

#30043

On 9/30/2014 4:38 PM, c123456749@gmail.com wrote:
> In documentation, what terminology should I use when I refer to the "this" object. Specifically, I have a class member that uses "this". And, I want to write clear documentation.

     Speaking for myself (de gustibus ...), in JavaDoc I'd rather see
"this" as an English pronoun than as a Java keyword, so I prefer
"this {@code Thing}" to "{@code this}":

	/**
	 * Assign a new {@code Frammis} to this {@code Thing} and
	 * de-assign any previously-assigned {@code Frammis}.
	 * @param frammis The {@code Frammis} to assign. Must not
	 * already be assigned to any {@code Thing}.
	 * @return The {@code Frammis} previously assigned to
	 * this {@code Thing}, or {@code null} if there was none.
	 * @throws NitwitException if {@code frammis} is already
	 * assigned to a {@code Thing}.
	 */
	public Frammis assignFrammis(Frammis frammis)
	    throws NitwitException
	{ ... }

     If constant repetition of "this {@code Thing}" starts to get
unpleasantly long, you might try using it only once per method and
switching to the shorter "{@code this}" for the rest of that method's
documentation. In the example above, you might use the shorter
form in the "@return" part.

     In the end, though, it comes down to trying to put yourself in
the reader's position, and asking yourself what would be clearest.
There's probably no single style that is best in all conceivable
cases. The style that works well for a straightforward method might
be suited for one that's more intricate, nor for the twenty paragraphs
of text and examples that document an entire class or package.

-- 
esosman@comcast-dot-net.invalid

[toc] | [prev] | [next] | [standalone]

#30044

On 9/30/2014 5:26 PM, Eric Sosman wrote:
>[...]
> The style that works well for a straightforward method might
> be suited for one that's more intricate, nor for the twenty paragraphs

     s/be/not be/

     Too much rewriting, not enough proofreading ...

-- 
esosman@comcast-dot-net.invalid

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.java.programmer

csiph-web