utils/jalopy/docs/inspector.html

   1
   2 <!--
   3  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.5)
   4  * Copyright (C) 2011 J Procter, AM Waterhouse, J Engelhardt, LM Lui, G Barton, M Clamp, S Searle
   5  *
   6  * This file is part of Jalview.
   7  *
   8  * Jalview is free software: you can redistribute it and/or
   9  * modify it under the terms of the GNU General Public License
  10  * as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
  11  *
  12  * Jalview is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty
  14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  * PURPOSE.  See the GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  18 -->
  19     <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
  20   <html><head>
  21       <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  22    <title>4.4.&nbsp;Code Inspector</title><link rel="stylesheet" href="site.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="manual.html" title="Jalopy User Manual"><link rel="up" href="settings.html" title="Chapter&nbsp;4.&nbsp;Settings"><link rel="previous" href="misc.html" title="4.3.13.&nbsp;Misc"><link rel="next" href="inspector-naming.html" title="4.4.2.&nbsp;Naming"><link rel="preface" href="dedication.html" title="Dedication"><link rel="preface" href="acknowledge.html" title="Acknowledgements"><link rel="preface" href="introduction.html" title="Introduction"><link rel="part" href="part-core.html" title="Part&nbsp;I.&nbsp;Jalopy core"><link rel="chapter" href="installation.html" title="Chapter&nbsp;1.&nbsp;Installation"><link rel="chapter" href="build.html" title="Chapter&nbsp;2.&nbsp;Building"><link rel="chapter" href="usage.html" title="Chapter&nbsp;3.&nbsp;Usage"><link rel="chapter" href="settings.html" title="Chapter&nbsp;4.&nbsp;Settings"><link rel="part" href="part-plugins.html" title="Part&nbsp;II.&nbsp;Plug-ins"><link rel="chapter" href="plugin-ant.html" title="Chapter&nbsp;5.&nbsp;Ant Plug-in task"><link rel="chapter" href="plugin-console.html" title="Chapter&nbsp;6.&nbsp;Console Application"><link rel="chapter" href="plugin-eclipse.html" title="Chapter&nbsp;7.&nbsp;Eclipse Plug-in"><link rel="chapter" href="plugin-jbuilder.html" title="Chapter&nbsp;8.&nbsp;JBuilder OpenTool"><link rel="chapter" href="plugin-jdev.html" title="Chapter&nbsp;9.&nbsp;JDeveloper Extension"><link rel="chapter" href="plugin-jedit.html" title="Chapter&nbsp;10.&nbsp;jEdit Plug-in"><link rel="chapter" href="plugin-netbeans.html" title="Chapter&nbsp;11.&nbsp;NetBeans/Sun ONE Studio module"><link rel="appendix" href="dependencies.html" title="Appendix&nbsp;A.&nbsp;Library Dependencies"><link rel="appendix" href="license-bsd.html" title="Appendix&nbsp;B.&nbsp;The Jalopy BSD License"><link rel="appendix" href="license-antlr.html" title="Appendix&nbsp;C.&nbsp;ANTLR SOFTWARE RIGHTS"><link rel="appendix" href="license-apache.html" title="Appendix&nbsp;D.&nbsp;The Apache Software License, Version 1.1"><link rel="appendix" href="license-gnu.html" title="Appendix&nbsp;E.&nbsp;GNU GENERAL PUBLIC LICENSE Version 2, June 1991"><link rel="appendix" href="license-gnu-doc.html" title="Appendix&nbsp;F.&nbsp;GNU Free Documentation License Version 1.1, March 2000"><link rel="appendix" href="license-common-public.html" title="Appendix&nbsp;G.&nbsp;Common Public License Version 1.0"><link rel="appendix" href="license-sun-public.html" title="Appendix&nbsp;H.&nbsp;SUN PUBLIC LICENSE Version 1.0"><link rel="index" href="ix01.html" title="Index"><link rel="subsection" href="inspector.html#d0e5095" title="4.4.1.&nbsp;General"><link rel="subsection" href="inspector-naming.html" title="4.4.2.&nbsp;Naming">
  23       <meta name="description" content="Jalopy Java Source Code Formatter Beautifier Pretty Printer">
  24       <meta http-equiv="pics-label" content='(pics-1.1 "http://www.icra.org/ratingsv02.html" l gen true for "http://jalopy.sf.net" r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true for "http://jalopy.sf.net" r (n 0 s 0 v 0 l 0))'>
  25     </head><body id="toppage" bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table width="700" border="0" cellpadding="0" cellspacing="0" align="left"><tbody><tr><td><table cellpadding="0" cellspacing="0" width="100%" style="border:1px solid #336699"><tbody><tr><td height="16"></td></tr><tr><td bgcolor="#3399cc" height="1"></td></tr><tr style="border:none"><td style="border:none"><table border="0" cellspacing="0" cellpadding="0"><tbody><tr><td class="logo">JALOPY</td><td class="sublogo" valign="bottom">Java Source Code Formatter Beautifier Pretty Printer</td></tr></tbody></table></td></tr><tr><td bgcolor="#3399cc" height="1"></td></tr><tr><td height="10"></td></tr><tr><td bgcolor="#ff8000" height="4"></td></tr><tr><td height="20" bgcolor="#336699" style="color:#ffffff;padding-left:10px"><a href="./index.html" class="navlink">Overview</a> &#149;
  26                     <a href="./download.html" class="navlink">Download</a> &#149;
  27                     <a href="./docs.html" class="navlink">Documentation</a> &#149;
  28                     <a href="./plugins.html" class="navlink">Plug-ins</a> &#149;
  29                     <a href="./links.html" class="navlink">Links</a> &#149;
  30                     <a href="./contact.html" class="navlink">Contact</a></td></tr><tr><td height="1" bgcolor="#ffffff"></td></tr></tbody></table></td></tr><tr valign="top"><td valign="top" bgcolor="#ffffff"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tbody><tr><td height="20" bgcolor="#faebd7" style="padding-left:15px"><a href="./features.html" class="navlink2">Features</a> |
  31                     <a href="./history.html" class="navlink2">History</a> |
  32                     <a href="./manual.html" class="navlink2">Manual</a> |
  33                     <a href="./faq.html" class="navlink2">FAQ</a> |
  34                     <a href="./api/index.html" class="navlink2">Javadoc</a></td></tr><tr><td height="20" bgcolor="#ffffff"></td></tr><tr><td bgcolor="#eeeecc" height="17" align="right" style="font-size:10px;padding-right:3px">
  35                     This page generated: <strong>June 8 2004</strong></td></tr></tbody></table><table border="0" width="100%" cellspacing="0" cellpadding="5"><tr><td><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4.4.&nbsp;Code Inspector</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="misc.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;4.&nbsp;Settings</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="inspector-naming.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="inspector"></a>4.4.&nbsp;Code Inspector</h2></div></div><div></div></div><a class="indexterm" name="d0e5090"></a><p>
  36 Provides the configuration facility for the Jalopy Code Inspector. The Code Inspector is
  37 able to inspect Java source files for naming convention violations and possible code
  38 weaknesses.
  39 </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e5095"></a>4.4.1.&nbsp;General</h3></div></div><div></div></div><p>
  40 Lets you control the general Code Inspector settings.
  41 </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e5100"></a>4.4.1.1.&nbsp;General</h4></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p>
  42 Enable
  43 </p><p>
  44 Lets you enable or disable the Code Inspector as a whole.
  45 </p></li></ul></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e5109"></a>4.4.1.2.&nbsp;Tips</h4></div></div><div></div></div><p>
  46 Lets you selectively choose what actions should be performed during inspection. Moving the
  47 mouse pointer onto a checkbox displays a minimalistic tooltip after a short delay.
  48 </p><div class="itemizedlist"><ul type="disc"><li><p>
  49 Tip 1 - Don't substitute another type for <tt class="classname">Object</tt> in the equals declaration
  50 </p><p>
  51 For a detailed discussion see <span class="emphasis"><em>Effective Java</em></span> [<a href="bi01.html#bloch01">Bloch01</a>], pp. 35.
  52 </p></li><li><p>
  53 Tip 2 - Object the general contract when overriding <tt class="literal">equals</tt>
  54 </p><p>
  55 For a detailed discussion see <span class="emphasis"><em>Effective Java</em></span> [<a href="bi01.html#bloch01">Bloch01</a>], pp. 25.
  56 </p></li><li><p>
  57 Tip 3 - Always override <tt class="literal">hashCode</tt> when you override <tt class="literal">equals</tt>
  58 </p><p>
  59 For a detailed discussion see <span class="emphasis"><em>Effective Java</em></span> [<a href="bi01.html#bloch01">Bloch01</a>], pp. 36.
  60 </p></li><li><p>
  61 Tip 4 - Always override <tt class="literal">equals</tt> when you override <tt class="literal">hashCode</tt>
  62 </p></li><li><p>
  63 Tip 5 - Always override <tt class="literal">toString</tt>
  64 </p><p>
  65 For a detailed discussion see <span class="emphasis"><em>Effective Java</em></span> [<a href="bi01.html#bloch01">Bloch01</a>], pp. 42.
  66 </p></li><li><p>
  67 Tip 6 - Use interfaces only to define types
  68 </p><p>
  69 For a detailed discussion see <span class="emphasis"><em>Effective Java</em></span> [<a href="bi01.html#bloch01">Bloch01</a>], pp. 89.
  70 </p></li><li><p>
  71 Tip 7 - Replace structures with classes
  72 </p><p>
  73 For a detailed discussion see <span class="emphasis"><em>Effective Java</em></span> [<a href="bi01.html#bloch01">Bloch01</a>], pp. 97.
  74 </p></li><li><p>
  75 Tip 8 - Return zero-length arrays, not <tt class="literal">nulls</tt>
  76 </p><p>
  77 For a detailed discussion see <span class="emphasis"><em>Effective Java</em></span> [<a href="bi01.html#bloch01">Bloch01</a>], pp. 134.
  78 </p></li><li><p>
  79 Tip 9 - Adhere to generally accepted naming conventions
  80 </p><p>
  81 For a detailed discussion see <span class="emphasis"><em>Effective Java</em></span> [<a href="bi01.html#bloch01">Bloch01</a>], pp. 165.
  82 </p></li><li><p>
  83 Tip 10 - Refer to objects by their interfaces
  84 </p><p>
  85 For a detailed discussion see <span class="emphasis"><em>Effective Java</em></span> [<a href="bi01.html#bloch01">Bloch01</a>], pp. 156.
  86 </p></li><li><p>
  87 Tip 11 - Never declare that a method "throws Exception"
  88 </p><p>
  89 For a detailed discussion see <span class="emphasis"><em>Effective Java</em></span> [<a href="bi01.html#bloch01">Bloch01</a>], pp. 181.
  90 </p></li><li><p>
  91 Tip 12 - Never declare that a method "throws Throwable"
  92 </p><p>
  93 For a detailed discussion see <span class="emphasis"><em>Effective Java</em></span> [<a href="bi01.html#bloch01">Bloch01</a>], pp. 181.
  94 </p></li><li><p>
  95 Tip 13 - Don't ignore exceptions
  96 </p><p>
  97 For a detailed discussion see <span class="emphasis"><em>Effective Java</em></span> [<a href="bi01.html#bloch01">Bloch01</a>], pp. 187.
  98 </p></li><li><p>
  99 Tip 14 - Never invoke <tt class="literal">wait</tt> outside a loop
 100 </p><p>
 101 For a detailed discussion see <span class="emphasis"><em>Effective Java</em></span> [<a href="bi01.html#bloch01">Bloch01</a>], pp. 201.
 102 </p></li><li><p>
 103 Tip 15 - Avoid thread groups
 104 </p><p>
 105 For a detailed discussion see <span class="emphasis"><em>Effective Java</em></span> [<a href="bi01.html#bloch01">Bloch01</a>], pp. 211.
 106 </p></li><li><p>
 107 Tip 16 - Document collection types
 108 </p><p>
 109 As long as there are no strong-typed collections (a.k.a. Java Generics support) available,
 110 it is best to document the object type of the items hold by a collection.
 111 </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">
 112 private static final List _favorableTypes = new ArrayList(20); // List of &lt;String&gt;
 113 </pre></td></tr></table></div><p></p></li><li><p>
 114 Tip 17 - Adhere to naming convention for collection types
 115 </p><p>
 116 If you use comments to document the object type of collection items, you should conform to
 117 a generally accepted naming convention.
 118 </p></li><li><p>
 119 Tip 18 - Avoid empty <tt class="literal">finally</tt> blocks
 120 </p><p>
 121 Empty <tt class="literal">finally</tt> blocks are of no use and may indicate programmer errors.
 122 </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">
 123 Writer writer = null;
 124
 125 try
 126 {
 127     writer = new BufferedWriter(new FileWriter(file));
 128     write.write(data);
 129 }
 130 catch (IOException ex)
 131 {
 132     System.err.println("file could not be written -- " + file);
 133 }
 134 finally
 135 {
 136 }
 137 </pre></td></tr></table></div><p>
 138 The programmer certainly wanted to close the <tt class="classname">Writer</tt> in the
 139 <tt class="literal">finally</tt> block to ensure that allocated system resources will be freed.
 140 </p></li><li><p>
 141 Tip 19 - Avoid variable shadowing
 142 </p><p>
 143 Variable shadowing should be avoided on general principle, as it tends to be confusing.
 144 </p><p>
 145 For more information about shadowing, see the
 146 Java Developer Connection (JDC) Tech Tips, October 10, 2000
 147 (<a href="http://developer.java.sun.com/developer/TechTips/2000/tt1010.html#tip2" target="_top">
 148 http://developer.java.sun.com/developer/TechTips/2000/tt1010.html#tip2</a>, subscription needed) or
 149 section 6.3.2, "Obscured Declarations," section 7.5.2,
 150 "Type-Import-on-Demand Declaration," section 8.4.6, "Inheritance, Overriding, and Hiding,"
 151 section 8.4.8.5, "Example: Invocation of Hidden Class Methods," and section 14.4.3,
 152 "Shadowing of Names by Local variables" in "The Java Language Specification Second
 153 Edition" by Gosling, Joy, Steele, and Bracha
 154 (<a href="http://java.sun.com/docs/books/jls/" target="_top">http://java.sun.com/docs/books/jls/)</a>.
 155 </p></li><li><p>
 156 Tip 20 - Add <span class="emphasis"><em>NOI18N</em></span> comment for String literals
 157 </p><p>
 158 Enabling this tip will cause warnings for all String literals without associated
 159 <tt class="literal">/* NOI18N */</tt> comment.
 160 </p><p>
 161 Internationalizing Java applications is often done with nifty tools that use marker
 162 comments to indicate that a given String literal should not be considered for localization.
 163 Most tools (at least the ones I know of) use trailing single-line comments which may not
 164 be very robust for processing with a formatting tool such as Jalopy. In contrast the author
 165 uses a multi-line comment of the form <tt class="literal">/* NOI18N */</tt> that gets directly
 166 placed after a String literal and will therefore always stuck with it.
 167 </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">
 168 FileDialog dialog = new FileDialog(this,
 169     ResourceBundle.getBundle(BUNDLE_NAME)
 170     .getString("BTN_SAVE_AS", FileDialog.SAVE); //$NON-NLS-1$
 171 </pre></td></tr></table></div><p>
 172 This trailing comment could be easily moved away from its String literal during formatting
 173 which would result in an unwanted notice on successive internationalization runs.
 174 </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">
 175 FileDialog dialog =
 176     new FileDialog(this,
 177                    ResourceBundle.getBundle(BUNDLE_NAME).
 178                                   getString("BTN_SAVE_AS",
 179                    FileDialog.SAVE); //$NON-NLS-1$
 180 </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">
 181 FileDialog dialog =
 182     new FileDialog(this,
 183                    ResourceBundle.getBundle(BUNDLE_NAME).
 184                                   getString("BTN_SAVE_AS" /* NOI18N */),
 185                    FileDialog.SAVE);
 186 </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">
 187             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>