416 lines
13 KiB
HTML
416 lines
13 KiB
HTML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html
|
|
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
"DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
<head>
|
|
<title>Class Design Checks</title>
|
|
<link rel="stylesheet" type="text/css" href="mystyle.css"/>
|
|
</head>
|
|
|
|
<body>
|
|
<!-- The header -->
|
|
<table border="0" width="100%" summary="header layout">
|
|
<tr>
|
|
<td><h1>Class Design Checks</h1></td>
|
|
<td align="right"><img src="logo.png" alt="Checkstyle Logo"/></td>
|
|
</tr>
|
|
</table>
|
|
<!-- content -->
|
|
<table border="0" width="100%" cellpadding="5" summary="body layout">
|
|
<tr>
|
|
<!--Left menu-->
|
|
<td class="menu" valign="top">
|
|
<ul>
|
|
<li>
|
|
<a href="#DesignForExtension">DesignForExtension</a>
|
|
</li>
|
|
<li>
|
|
<a href="#FinalClass">FinalClass</a>
|
|
</li>
|
|
<li>
|
|
<a href="#HideUtilityClassConstructor">HideUtilityClassConstructor</a>
|
|
</li>
|
|
<li>
|
|
<a href="#InterfaceIsType">InterfaceIsType</a>
|
|
</li>
|
|
<li>
|
|
<a href="#MutableException">MutableException</a>
|
|
</li>
|
|
<li>
|
|
<a href="#ThrowsCount">ThrowsCount</a>
|
|
</li>
|
|
<li>
|
|
<a href="#VisibilityModifier">VisibilityModifier</a>
|
|
</li>
|
|
</ul>
|
|
</td>
|
|
<!--Content-->
|
|
<td class="content" valign="top" align="left">
|
|
<a name="VisibilityModifier"></a><h2>VisibilityModifier</h2>
|
|
<p class="body">
|
|
Checks visibility of class members. Only static final members
|
|
may be public; other class members must be private unless
|
|
property <span class="code">protectedAllowed</span> or <span
|
|
class="code">packageAllowed</span> is set.
|
|
</p>
|
|
|
|
<p class="body">
|
|
Public members are not flagged if the name matches the public
|
|
member regular expression (contains <span
|
|
class="code">"^serialVersionUID$"</span> by default). Note:
|
|
Checkstyle 2 used to include <span
|
|
class="code">"^f[A-Z][a-zA-Z0-9]*$"</span> in the default
|
|
pattern to allow CMP for EJB 1.1 with the default settings.
|
|
With EJB 2.0 it is not longer necessary to have public access
|
|
for persistent fields, hence the default has been changed.
|
|
</p>
|
|
<p class="body">
|
|
Rationale: Enforce encapsulation.
|
|
</p>
|
|
|
|
|
|
<h4>Properties</h4>
|
|
<table width="100%" border="1" cellpadding="5" class="body">
|
|
<tr class="header">
|
|
<th>name</th>
|
|
<th>description</th>
|
|
<th>type</th>
|
|
<th>default value</th>
|
|
</tr>
|
|
<tr>
|
|
<td>packageAllowed</td>
|
|
<td>whether package visible members are allowed</td>
|
|
<td><a href="property_types.html#boolean">boolean</a></td>
|
|
<td><span class="default">false</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>protectedAllowed</td>
|
|
<td>whether protected members are allowed</td>
|
|
<td><a href="property_types.html#boolean">boolean</a></td>
|
|
<td><span class="default">false</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>publicMemberPattern</td>
|
|
<td>pattern for public members that should be ignored</td>
|
|
<td><a href="property_types.html#regexp">regular expression</a></td>
|
|
<td><span class="default">^serialVersionUID$</span></td>
|
|
</tr>
|
|
</table>
|
|
<h4>Examples</h4>
|
|
<p class="body">
|
|
To configure the check:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="VisibilityModifier"/>
|
|
</pre>
|
|
<p class="body">
|
|
To configure the check so that it allows package visible members:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="VisibilityModifier">
|
|
<property name="packageAllowed" value="true"/>
|
|
</module>
|
|
</pre>
|
|
<p class="body">
|
|
To configure the check so that it allows no public members:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="VisibilityModifier">
|
|
<property name="publicMemberPattern" value="^$"/>
|
|
</module>
|
|
</pre>
|
|
<h4>Package</h4>
|
|
<p class="body">
|
|
com.puppycrawl.tools.checkstyle.checks.design
|
|
</p>
|
|
<h4>Parent Module</h4>
|
|
<p class="body">
|
|
<a href="config.html#treewalker">TreeWalker</a>
|
|
</p>
|
|
|
|
<!-- --> <a name="FinalClass"></a><h2>FinalClass</h2>
|
|
|
|
<p class="body">
|
|
Checks that a class which has only private constructors is declared as final.
|
|
</p>
|
|
<h4>Example</h4>
|
|
<p class="body">
|
|
To configure the check:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="FinalClass"/>
|
|
</pre>
|
|
<h4>Package</h4>
|
|
<p class="body">
|
|
com.puppycrawl.tools.checkstyle.checks.design
|
|
</p>
|
|
<h4>Parent Module</h4>
|
|
<p class="body">
|
|
<a href="config.html#treewalker">TreeWalker</a>
|
|
</p>
|
|
<!-- --> <a name="InterfaceIsType"></a> <h2>InterfaceIsType</h2> <h4>Description</h4>
|
|
<p class="body">
|
|
Implements Bloch, Effective Java, Item 17 -
|
|
Use Interfaces only to define types.
|
|
</p>
|
|
|
|
<p class="body">
|
|
According to Bloch, an interface should describe a <em>type</em>.
|
|
It is therefore inappropriate to define an interface that does not
|
|
contain any methods but only constants. The Standard class
|
|
<a href="http://java.sun.com/j2se/1.4.1/docs/api/javax/swing/SwingConstants.html">javax.swing.SwingConstants</a>
|
|
is an example of a class that would be flagged by this check.
|
|
</p>
|
|
|
|
<p class="body">
|
|
The check can be configured to also disallow marker interfaces like
|
|
<code>java.io.Serializable</code>, that do not contain methods or
|
|
constants at all.
|
|
</p>
|
|
|
|
<h4>Properties</h4>
|
|
<table width="100%" border="1" cellpadding="5" class="body">
|
|
<tr class="header">
|
|
<th>name</th>
|
|
<th>description</th>
|
|
<th>type</th>
|
|
<th>default value</th>
|
|
</tr>
|
|
<tr>
|
|
<td>allowMarkerInterfaces</td>
|
|
<td>Controls whether marker interfaces like Serializable are allowed.</td>
|
|
<td><a href="property_types.html#boolean">Boolean</a></td>
|
|
<td><span class="default">true</span></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>Examples</h4>
|
|
<p class="body">
|
|
To configure the check:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="InterfaceIsType"/>
|
|
</pre>
|
|
<h4>Package</h4>
|
|
<p class="body">
|
|
com.puppycrawl.tools.checkstyle.checks.design
|
|
</p>
|
|
<h4>Parent Module</h4>
|
|
<p class="body">
|
|
<a href="config.html#treewalker">TreeWalker</a>
|
|
</p>
|
|
|
|
<!-- --> <a name="HideUtilityClassConstructor"></a> <h2>HideUtilityClassConstructor</h2> <h4>Description</h4>
|
|
<p class="body">
|
|
Make sure that utility classes (classes that contain only static methods)
|
|
do not have a public constructor.
|
|
</p>
|
|
<p class="body">
|
|
Rationale: Instantiating utility classes does not make sense.
|
|
Hence the constructors should either be private or (if you
|
|
want to allow subclassing) protected. A common mistake is forgetting
|
|
to hide the default constructor.
|
|
</p>
|
|
<p class="body">
|
|
If you make the constructor protected you may want to consider
|
|
the following constructor implementation technique to disallow
|
|
instantiating subclasses:
|
|
</p>
|
|
<pre class="body">
|
|
public class StringUtils // not final to allow subclassing
|
|
{
|
|
protected StringUtils() {
|
|
throw new UnsupportedOperationException(); // prevents calls from subclass
|
|
}
|
|
|
|
public static int count(char c, String s) {
|
|
// ...
|
|
}
|
|
}
|
|
</pre>
|
|
<h4>Examples</h4>
|
|
<p class="body">
|
|
To configure the check:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="HideUtilityClassConstructor"/>
|
|
</pre>
|
|
<h4>Package</h4>
|
|
<p class="body">
|
|
com.puppycrawl.tools.checkstyle.checks.design
|
|
</p>
|
|
<h4>Parent Module</h4>
|
|
<p class="body">
|
|
<a href="config.html#treewalker">TreeWalker</a>
|
|
</p>
|
|
|
|
<!-- --> <a name="DesignForExtension"></a> <h2>DesignForExtension</h2> <h4>Description</h4>
|
|
<p class="body">
|
|
Checks that classes are designed for extension.
|
|
More specifically, it enforces a programming style
|
|
where superclasses provide empty "hooks" that can be
|
|
implemented by subclasses.
|
|
</p>
|
|
|
|
<p class="body">
|
|
The exact rule is that nonprivate, nonstatic methods of classes that
|
|
can be subclassed must either be
|
|
</p>
|
|
<ul class="body">
|
|
<li>abstract or</li>
|
|
<li>final or</li>
|
|
<li>have an empty implementation</li>
|
|
</ul>
|
|
|
|
<p class="body">
|
|
Rationale: This API design style protects superclasses against beeing broken by
|
|
subclasses. The downside is that subclasses are limited in their flexibility,
|
|
in particular they cannot prevent execution of code in the superclass, but that also
|
|
means that subclasses cannot corrupt the state of the superclass by forgetting to
|
|
call the super method.
|
|
</p>
|
|
|
|
<h4>Properties</h4>
|
|
None.
|
|
|
|
<h4>Examples</h4>
|
|
<p class="body">
|
|
To configure the check:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="DesignForExtension"/>
|
|
</pre>
|
|
<h4>Package</h4>
|
|
<p class="body">
|
|
com.puppycrawl.tools.checkstyle.checks.design
|
|
</p>
|
|
<h4>Parent Module</h4>
|
|
<p class="body">
|
|
<a href="config.html#treewalker">TreeWalker</a>
|
|
</p>
|
|
|
|
<!-- --> <a name="MutableException"></a> <h2>MutableException</h2> <h4>Description</h4>
|
|
<p class="body">
|
|
Ensures that exceptions (defined as any class name conforming
|
|
to some regular expression) are immutable. That is, have only
|
|
final fields.
|
|
</p>
|
|
|
|
<p class="body">
|
|
The current algorithm is very simple it checks that all
|
|
members of exception are final. User can still mutates an
|
|
exception's instance (e.g. Throwable has
|
|
setStackTrace(StackTraceElement[] stackTrace) method which
|
|
changes stack trace). But, at least, all information provided
|
|
by this exception type is unchangable.
|
|
</p>
|
|
|
|
<p class="body">
|
|
Rationale:
|
|
Exception instances should represent an error
|
|
condition. Having non final fields not only allows the
|
|
state to be modified by accident and therefore mask the
|
|
original condition but also allows developers to
|
|
accidentally forget to initialise state thereby leading
|
|
to code catching the exception to draw incorrect
|
|
conclusions based on the state.
|
|
</p>
|
|
|
|
<h4>Properties</h4>
|
|
<table width="100%" border="1" cellpadding="5" class="body">
|
|
<tr class="header">
|
|
<th>name</th>
|
|
<th>description</th>
|
|
<th>type</th>
|
|
<th>default value</th>
|
|
</tr>
|
|
<tr>
|
|
<td>format</td>
|
|
<td>pattern for name of exception class.</td>
|
|
<td><a href="property_types.html#regexp">regular expression</a></td>
|
|
<td><span class="default">^.*Exception$|^.*Error$</span></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>Examples</h4>
|
|
<p class="body">
|
|
To configure the check:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="MutableException"/>
|
|
</pre>
|
|
<h4>Package</h4>
|
|
<p class="body">
|
|
com.puppycrawl.tools.checkstyle.checks.design
|
|
</p>
|
|
<h4>Parent Module</h4>
|
|
<p class="body">
|
|
<a href="config.html#treewalker">TreeWalker</a>
|
|
</p>
|
|
|
|
<!-- --> <a name="ThrowsCount"></a> <h2>ThrowsCount</h2> <h4>Description</h4>
|
|
<p class="body">
|
|
Restricts throws statements to a specified count (default = 1).
|
|
</p>
|
|
|
|
<p class="body">
|
|
Rationale:
|
|
Exceptions form part of a methods interface. Declaring
|
|
a method to throw too many differently rooted
|
|
exceptions makes exception handling onerous and leads
|
|
to poor programming practices such as catch
|
|
(Exception). This check forces developers to put
|
|
exceptions into a heirachy such that in the simplest
|
|
case, only one type of exception need be checked for by
|
|
a caller but allows any sub-classes to be caught
|
|
specifically if necessary.
|
|
</p>
|
|
|
|
<h4>Properties</h4>
|
|
<table width="100%" border="1" cellpadding="5" class="body">
|
|
<tr class="header">
|
|
<th>name</th>
|
|
<th>description</th>
|
|
<th>type</th>
|
|
<th>default value</th>
|
|
</tr>
|
|
<tr>
|
|
<td>max</td>
|
|
<td>maximum allowed number of throws statments</td>
|
|
<td><a href="property_types.html#integer">Integer</a></td>
|
|
<td><span class="default">1</span></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>Examples</h4>
|
|
<p class="body">
|
|
To configure the check so that it doesn't allow more than two
|
|
throws per method:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="ThrowsCount">
|
|
<property name="max" value="2"/>
|
|
</module>
|
|
</pre>
|
|
<h4>Package</h4>
|
|
<p class="body">
|
|
com.puppycrawl.tools.checkstyle.checks.design
|
|
</p>
|
|
<h4>Parent Module</h4>
|
|
<p class="body">
|
|
<a href="config.html#treewalker">TreeWalker</a>
|
|
</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr />
|
|
<div><a href="index.html">Back to the Checkstyle Home Page</a></div>
|
|
<p class="copyright">
|
|
Copyright © 2002-2004 Oliver Burn. All rights Reserved.
|
|
</p>
|
|
|
|
</body>
|
|
</html>
|