inspector.html

This the README for the Eclipse Plug-in distribution of the Jalopy Java Source Code Formatter.

Tip 15 - Avoid thread groups
</p><p>
For a detailed discussion see <span class="emphasis"><em>Effective Java</em></span> [<a href="bi01.html#bloch01">Bloch01</a>], pp. 211.
</p></li><li><p>
Tip 16 - Document collection types
</p><p>
As long as there are no strong-typed collections (a.k.a. Java Generics support) available,
it is best to document the object type of the items hold by a collection.
</p><div class="example"><a name="inspector-tip16"></a><p class="title"><b>Example&nbsp;4.154.&nbsp;Collection comment</b></p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="programlisting">
private static final List _favorableTypes = new ArrayList(20); // List of &lt;String&gt;
</pre></td></tr></table></div><p></p></li><li><p>
Tip 17 - Adhere to naming convention for collection types
</p><p>
If you use comments to document the object type of collection items, you should conform to
a generally accepted naming convention.
</p></li><li><p>
Tip 18 - Avoid empty <tt class="literal">finally</tt> blocks
</p><p>
Empty <tt class="literal">finally</tt> blocks are of no use and may indicate programmer errors.
</p><div class="example"><a name="inspector-tip18"></a><p class="title"><b>Example&nbsp;4.155.&nbsp;Empty <tt class="literal">finally</tt> block</b></p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="programlisting">
Writer writer = null;

try
{
    writer = new BufferedWriter(new FileWriter(file));
    write.write(data);
}
catch (IOException ex)
{
    System.err.println("file could not be written -- " + file);
}
finally
{
}
</pre></td></tr></table></div><p>
The programmer certainly wanted to close the <tt class="classname">Writer</tt> in the
<tt class="literal">finally</tt> block to ensure that allocated system resources will be freed.
</p></li><li><p>
Tip 19 - Avoid variable shadowing
</p><p>
Variable shadowing should be avoided on general principle, as it tends to be confusing.
</p><p>
For more information about shadowing, see the
Java Developer Connection (JDC) Tech Tips, October 10, 2000
(<a href="http://developer.java.sun.com/developer/TechTips/2000/tt1010.html#tip2" target="_top">
http://developer.java.sun.com/developer/TechTips/2000/tt1010.html#tip2</a>, subscription needed) or
section 6.3.2, "Obscured Declarations," section 7.5.2,
"Type-Import-on-Demand Declaration," section 8.4.6, "Inheritance, Overriding, and Hiding,"
section 8.4.8.5, "Example: Invocation of Hidden Class Methods," and section 14.4.3,
"Shadowing of Names by Local variables" in "The Java Language Specification Second
Edition" by Gosling, Joy, Steele, and Bracha
(<a href="http://java.sun.com/docs/books/jls/" target="_top">http://java.sun.com/docs/books/jls/)</a>.
</p></li><li><p>
Tip 20 - Add <span class="emphasis"><em>NOI18N</em></span> comment for String literals
</p><p>
Enabling this tip will cause warnings for all String literals without associated
<tt class="literal">/* NOI18N */</tt> comment.
</p><p>
Internationalizing Java applications is often done with nifty tools that use marker
comments to indicate that a given String literal should not be considered for localization.
Most tools (at least the ones I know of) use trailing single-line comments which may not
be very robust for processing with a formatting tool such as Jalopy. In contrast the author
uses a multi-line comment of the form <tt class="literal">/* NOI18N */</tt> that gets directly
placed after a String literal and will therefore always stuck with it.
</p><div class="example"><a name="inspector-tip20"></a><p class="title"><b>Example&nbsp;4.156.&nbsp;$NON-NLS-1$ comment</b></p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="programlisting">
FileDialog dialog = new FileDialog(this,
    ResourceBundle.getBundle(BUNDLE_NAME)
    .getString("BTN_SAVE_AS", FileDialog.SAVE); //$NON-NLS-1$
</pre></td></tr></table></div><p>
This trailing comment could be easily moved away from its String literal during formatting
which would result in an unwanted notice on successive internationalization runs.
</p><div class="example"><a name="inspector-tip20a"></a><p class="title"><b>Example&nbsp;4.157.&nbsp;$NON-NLS-1$ comment</b></p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="programlisting">
FileDialog dialog =
    new FileDialog(this,
                   ResourceBundle.getBundle(BUNDLE_NAME).
                                  getString("BTN_SAVE_AS",
                   FileDialog.SAVE); //$NON-NLS-1$
</pre></td></tr></table></div><p></p><div class="example"><a name="inspector-tip20b"></a><p class="title"><b>Example&nbsp;4.158.&nbsp;NOI18N comment</b></p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="programlisting">
FileDialog dialog =
    new FileDialog(this,
                   ResourceBundle.getBundle(BUNDLE_NAME).
                                  getString("BTN_SAVE_AS" /* NOI18N */),
                   FileDialog.SAVE);
</pre></td></tr></table></div><p></p></li></ul></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="misc.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="settings.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="inspector-naming.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4.3.13.&nbsp;Misc&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;4.4.2.&nbsp;Naming</td></tr></table></div></td></tr></table></td></tr><tr><td bgcolor="#eeeecc" height="17" style="font-size:9px;padding-left:5px"><a href="#toppage">to top</a></td></tr><tr><td height="30"><br></td></tr><tr><td height="3"></td></tr><tr><td bgcolor="#336699" height="1"></td></tr><tr><td height="1"></td></tr><tr><td bgcolor="#336699" height="16"></td></tr><tr><td bgcolor="#ff9966" height="4"></td></tr><tr><td class="footer" align="center" height="15" valign="middle">
            Copyright &copy; 2001-2004, <a class="footer" href="./contact.html">Marco Hunsicker</a>. All rights reserved. Hosted by <a href="http://sourceforge.net">SourceForge.net</a></td></tr></tbody></table><img src="http://sourceforge.net/sflogo.php?group_id=45216&amp;type=1" width="1" height="1" border="0" hspace="0" vspace="0" alt=""></body></html>