Path: csiph.com!x330-a1.tempe.blueboxinc.net!usenet.pasdenom.info!news.lightlink.com!news.iecc.com!border3.nntp.dca.giganews.com!Xl.tags.giganews.com!border1.nntp.dca.giganews.com!nntp.giganews.com!local2.nntp.dca.giganews.com!nntp.earthlink.com!news.earthlink.com.POSTED!not-for-mail NNTP-Posting-Date: Wed, 05 Oct 2011 07:45:35 -0500 Date: Wed, 05 Oct 2011 05:45:28 -0700 From: Patricia Shanahan User-Agent: Mozilla/5.0 (Windows NT 5.2; WOW64; rv:7.0.1) Gecko/20110929 Thunderbird/7.0.1 MIME-Version: 1.0 Newsgroups: comp.lang.java.programmer Subject: Re: @see scope References: <97kl87pgsfv7f3klmucsso1bikkcicj3hj@4ax.com> <18470557.141.1317755716841.JavaMail.geo-discussion-forums@prfc6> In-Reply-To: Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Message-ID: Lines: 44 X-Usenet-Provider: http://www.giganews.com NNTP-Posting-Host: 70.230.204.200 X-Trace: sv3-Ut7iM4PNOMNzoTUrhanOAYRLe5ibNCQrkcH4Cr3OSHxfkUUGV5TP6Cq7mBH1PIzRXsnKk77cajwJHR7!5LQdG7tJTayN4B6JjhV1CTUgWBBdXKf6TbHm1qB7QN5Aer+VHchasf5BwOPtXGTx4NTKRDQHHg7c!9uDNyKyBkUQlbQU/jCyE9wv4a3qbQZccMo9HYGprPZKUZuQ= X-Abuse-and-DMCA-Info: Please be sure to forward a copy of ALL headers X-Abuse-and-DMCA-Info: Otherwise we will be unable to process your complaint properly X-Postfilter: 1.3.40 X-Original-Bytes: 3463 Xref: x330-a1.tempe.blueboxinc.net comp.lang.java.programmer:8563 On 10/5/2011 3:20 AM, Paul Cager wrote: > On Oct 4, 8:15 pm, Lew 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