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

Groups > comp.lang.java.programmer > #8563

Re: @see scope

Show all headers | View raw

On 10/5/2011 3:20 AM, Paul Cager wrote:
> On Oct 4, 8:15 pm, Lew<lewbl...@gmail.com>  wrote:
>> ...
>> The separate question of Javadocs for private methods is a no-brainer.
>> ...
>>
>> So sure, Javadoc-comment the restricted-scope methods, too.  You don't have to gen
>> Javadocs just because the comments are there, but it sure is handy when you want to.
>
> Another advantage of Javadocing private methods is that code
> completion will show the method's Javadoc as a tool-tip (at least in
> Eclipse). Of course there are arguments that your code should be self-
> documenting and so the comments should be unnecessary. I'll leave that
> argument for another day.

Self-documenting code as a substitute for class and method comments only
works in programs that are so extremely small that a programmer can read
all the code in order to make one change or fix one bug.

Now consider a reasonably large program. Suppose you are considering a
change to some method, and need to understand its code. As you read
along, you come to calls to other methods. Knowing what those methods do
is essential to understanding the code doing the method calls. There is,
however, no need to know how they do it.

If they are Javadoc commented, it is as easy as putting the mouse
pointer over the name of a called method, and reading the tool-tip that
pops up. That can be done without interrupting the train of thought
about the current method.

If they are commented, but not Javadoc, it means bringing up the
declaration of the called method and reading its comment. That is a bit
more of a burden, but still manageable.

If they are only "self-documenting" it means suspending reading the
current method and instead reading the code for each method it calls in
order to find out what it does. Reading that code may depend on what
knowing what methods it calls do. The process becomes a deeply recursive
distraction from the method that actually needs to be understood.

Good method names are great mnemonics, but rarely give all the needed
information.

Patricia

Back to comp.lang.java.programmer | Previous | Next — Previous in thread | Next in thread | Find similar

Thread

@see scope Roedy Green <see_website@mindprod.com.invalid> - 2011-10-04 02:26 -0700
  Re: @see scope Andreas Leitgeb <avl@gamma.logic.tuwien.ac.at> - 2011-10-04 11:20 +0000
    Re: @see scope Patricia Shanahan <pats@acm.org> - 2011-10-04 06:57 -0700
      Re: @see scope Andreas Leitgeb <avl@gamma.logic.tuwien.ac.at> - 2011-10-04 16:36 +0000
  Re: @see scope Roedy Green <see_website@mindprod.com.invalid> - 2011-10-04 10:28 -0700
    Re: @see scope Lew <lewbloch@gmail.com> - 2011-10-04 12:15 -0700
      Re: @see scope Paul Cager <paul.cager@googlemail.com> - 2011-10-05 03:20 -0700
        Re: @see scope Patricia Shanahan <pats@acm.org> - 2011-10-05 05:45 -0700
  Re: @see scope Jan Burse <janburse@fastmail.fm> - 2011-10-05 15:05 +0200

csiph-web