Menu
▾
▴
[Gridarta-commit] SF.net SVN: gridarta: [1004] trunk/src/doc/dev/codeStyle.xhtml
|
From: <chr...@us...> - 2006-12-10 13:34:07
|
Revision: 1004
http://svn.sourceforge.net/gridarta/?rev=1004&view=rev
Author: christianhujer
Date: 2006-12-10 05:34:04 -0800 (Sun, 10 Dec 2006)
Log Message:
-----------
Documented current code style / error policy.
Modified Paths:
--------------
trunk/src/doc/dev/codeStyle.xhtml
Modified: trunk/src/doc/dev/codeStyle.xhtml
===================================================================
--- trunk/src/doc/dev/codeStyle.xhtml 2006-12-10 13:09:50 UTC (rev 1003)
+++ trunk/src/doc/dev/codeStyle.xhtml 2006-12-10 13:34:04 UTC (rev 1004)
@@ -58,5 +58,80 @@
<li>work exception, stream closed, close won't throw an exception (API spec) - interested in work exception.</li>
<li>work exception, stream undefined, close exception - close exception is probably as good as work exception.</li>
</ul>
+ <h2>The Rules in Detail</h2>
+ <p>
+ This description describes the inspection profile "No errors allowed here".
+ As the name already suggests, this inspection profile must always run without errors.
+ The purpose of this inspection profile is to prevent a regression of code quality.
+ Currently it is quite small.
+ New rules will be added whenever a certain level of cleanness and style is reached.
+ </p>
+ <p>
+ The following list explains the current rules, listed in a way that you can easily identify them in IntelliJ IDEA.
+ It serves two purposes.
+ One is to explain the rationale of the configured rules.
+ The other is to enable developers that do not use IntelliJ IDEA / InspectionGadgets to know what the rules are to be able to perform the same verifications.
+ </p>
+ <ul>
+ <li>
+ Inspections
+ <ul>
+ <li>
+ Class structure
+ <dl>
+ <dt>Missing @Deprecated annotation</dt>
+ <dd>
+ Makes sure that deprecated members that are documented as deprecated in Javadoc (<code>@deprecated</code> javadoc tag) are also annotated as <code>@Deprecated</code> in the source code.
+ <br />
+ Background:
+ Future compiler versions (jdk 1.6 or jdk 1.7) might stop to parse javadoc comments.
+ To get the deprecation information into the class file, the annotation must be used then.
+ Also, deprecation information might only be fully reflective on 1.5 or later if it was declared with the annotation.
+ </dd>
+ <dt>Missing @Override annotation</dt>
+ <dd>
+ Makes sure that members that override members from a class (not implement from an interface) are annotated as
+ <code>@Override</code> in the source code.
+ <br />
+ Background:
+ A missing <code>@Override</code> isn't an error by itself.
+ But the opposite situation, an <code>@Override</code> when nothing is overridden is an error.
+ That is useful for finding typos when wanting to override a method.
+ E.g. if you override <code>toString()</code> using <code>@Override public String tostring()</code> (not the typo), the compiler will be able to report this as an error.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ General
+ <dl>
+ <dt>Declaration has javadoc problems</dt>
+ <dd>
+ Makes sure that a javadoc comment that is present also has a certain level of technical quality.
+ Currently the following omissions are treated as errors:
+ <code>@author</code> for top level classes, periods in briefs, <code>@return</code> for methods, <code>@param</code> and <code>ŧrhwos</code> or <code>@exception</code> for methods and constructors.
+ Unknown javadoc tags are also reported (<code>@note</code> and similar extension tags are known to this inspection and won't cause false positives).
+ <br />
+ Though it would be possible to ignore deprecated elements, they're not.
+ Even if an element is deprecated, it must still be documented properly and without errors.
+ </dd>
+ <dt>Declaration has problems in javadoc references</dt>
+ <dd>
+ Makes sure that references in javadoc comments (<code>{@link ...}</code> and eventually <code>@see ...</code>) can be resolved.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ Inheritance issues
+ <dl>
+ <dt>Abstract method with missing implementations</dt>
+ <dd>
+ The compiler would of course report this in the subclasses that miss the implementation.
+ This inspection supports you while editing or if you're too lazy to perform a build prior to a commit.
+ </dd>
+ </dl>
+ </li>
+ </ul>
+ </li>
+ </ul>
</body>
</html>
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
