FindBugsHowto

Revision as of 14:16, 11 December 2012 (view source) Phejl (Talk | contribs) (→Suppressing warnings) ← Older edit		Current revision as of 15:14, 30 January 2013 (view source) Phejl (Talk | contribs) (→Suppressing warnings)
(17 intermediate revisions not shown)
Line 3:		Line 3:
	This document describes how FindBugs is used during the development of NetBeans.		This document describes how FindBugs is used during the development of NetBeans.
-
-	====FindBugs build jobs====
-
-	There are jobs that run FindBugs regularly on the NetBeans source code. The jobs operate on the per-team basis, so evaluation of failures can also be done on the per-team basis. The jobs are available on this URL: http://qa-findbugs.netbeans.org/.
-
-	There is also a job that runs FindBugs on the entire codebase, aggregated across all teams: http://qa-findbugs.netbeans.org/job/All-FindBugs/
-
-	The goal is to have no high priority FindBugs warnings, and to maintain this state in the long run.
	====Running FindBugs locally====		====Running FindBugs locally====
Line 21:		Line 13:
	</pre>		</pre>
-	This will produce the findbugs report file in <pre>$basedir/build/findbugs/org-netbeans-modules-your-module.xml</pre> and fails if at least one warning was discovered. No file is created if there is no problem in the tested module.	+	This will produce the findbugs report file in <pre>nbbuild/build/findbugs/org-netbeans-modules-your-module.xml</pre> and fails if at least one warning was discovered. No file is created if there is no problem in the tested module.
-	There is also a target in <pre>nbbuild</pre> to execute the test for all modules in a cluster at once:	+
		+	There is also a target in <code>nbbuild</code> to execute the test for all modules in a cluster at once:
	<pre>		<pre>
Line 33:		Line 26:
	====Evaluating FindBugs warnings====		====Evaluating FindBugs warnings====
-	The report containing FindBugs warnings can be viewed using the FindBugs UI. This tool can be downloaded from the FindBugs website: http://findbugs.sourceforge.net/. After installing FindBugs, you can run the tool using the <pre>findbugs[.bat]</pre> script in the <tt>{bin</tt>} directory. In the FindBugs UI, you may want to sort the issues by priority, by dragging the labels at the top left.	+	The report containing FindBugs warnings can be viewed using the FindBugs UI. This tool can be downloaded from the FindBugs website: http://findbugs.sourceforge.net/. After installing FindBugs, you can run the tool using the <pre>findbugs[.bat]</pre> script in the <code>bin</code> directory. In the FindBugs UI, you may want to sort the issues by priority, by dragging the labels at the top left.
	====Suppressing warnings====		====Suppressing warnings====
-	In some cases, you may want to suppress a particular warning, rather than fix it. In such a case, you can do the following:	+	In some cases, you may want to suppress a particular warning, rather than fix it. Always think twice about suppressing as FindBugs is usually right. If you really know it is a false warning you can do the following:
	# Make sure your module uses the Common Annotations module (api.annotations.common).		# Make sure your module uses the Common Annotations module (api.annotations.common).
-	# Find the id of the warning you want to suppress. Open the FindBugs report in a text editor, and find the <BugInstance> element for your warning. The value of the <tt>{type</tt>} attribute of this element is your warning id.	+	# Find the id of the warning you want to suppress. Open the FindBugs report in a text editor, and find the <BugInstance> element for your warning. The value of the <code>type</code> attribute of this element is your warning id. The warning id is also displayed in FindBugs UI:<br>[[File:FindbugsBugId.png|800px]]
-	# Add the following annotation to the code (method, class, instance variable, local variable etc.) in which you want to suppress the warning: <pre>@org.netbeans.api.annotations.common.SuppressWarnings("your_warning_id")</pre>. There is an API enhancement [http://netbeans.org/bugzilla/show_bug.cgi?id=221381] which adds a justification attribute to the annotation. Once in trunk the code might look like this:<pre>@org.netbeans.api.annotations.common.SuppressWarnings("your_warning_id", justification="Explanation why this is false warning")</pre>. Until then use following pattern:<pre>@org.netbeans.api.annotations.common.SuppressWarnings("your_warning_id") // justification="Explanation why this is false warning"</pre>	+	# Add the following annotation to the code (method, class, instance variable, local variable etc.) in which you want to suppress the warning: <pre>@org.netbeans.api.annotations.common.SuppressWarnings(value="your_warning_id", justification="Explanation why this is false warning")</pre>
-		+	# It is good to be consistent when justifying the same type of things.
-	====Open issues====	+
-		+
-	* There are many warnings that are reported as errors, but given the exact usage in NetBeans, they don't correspond to real bugs. For example, in the NetBeans codebase, often URLs are stored in collections, which results in a high priority FindBugs warning, however in practice, this may not be a bug. How should such warnings be treated? Should we turn the check off? Should we suppress the particular instance of the warning? Should we still try to fix? Should we just ignore them and leave them in the report?	+
-	* Some warnings appear in generated code, and addressing them requires more work - we need to change the code generator, which is not always straightforward. For example, <pre>schema2beans</pre> generates code that compares strings using <tt>{==</tt>}, which results in a FindBugs warning. It probably does not represent a real bug. How should we deal with such warnings?	+
	====Additional information====		====Additional information====
	* The [[SignatureTest | SignatureTest]] also helps to maintain high quality of NetBeans code.		* The [[SignatureTest | SignatureTest]] also helps to maintain high quality of NetBeans code.
-	* Jarda's original [[FindBugsTests | FindBugsTests]] page.

---

Current revision as of 15:14, 30 January 2013

How to use FindBugs with NetBeans sources

This document describes how FindBugs is used during the development of NetBeans.

Running FindBugs locally

For every NetBeans module, you can run the findbugs check by typing:

cd your.module
ant findbugs

This will produce the findbugs report file in

nbbuild/build/findbugs/org-netbeans-modules-your-module.xml

and fails if at least one warning was discovered. No file is created if there is no problem in the tested module.

There is also a target in nbbuild to execute the test for all modules in a cluster at once:

ant -f nbbuild/build.xml findbugs-cluster

This produces the output files for each module with a problem in

nbbuild/build/findbugs/

directory.

Evaluating FindBugs warnings

The report containing FindBugs warnings can be viewed using the FindBugs UI. This tool can be downloaded from the FindBugs website: http://findbugs.sourceforge.net/. After installing FindBugs, you can run the tool using the

findbugs[.bat]

script in the bin directory. In the FindBugs UI, you may want to sort the issues by priority, by dragging the labels at the top left.

Suppressing warnings

In some cases, you may want to suppress a particular warning, rather than fix it. Always think twice about suppressing as FindBugs is usually right. If you really know it is a false warning you can do the following:

1. Make sure your module uses the Common Annotations module (api.annotations.common).
2. Find the id of the warning you want to suppress. Open the FindBugs report in a text editor, and find the <BugInstance> element for your warning. The value of the type attribute of this element is your warning id. The warning id is also displayed in FindBugs UI:
   
3. Add the following annotation to the code (method, class, instance variable, local variable etc.) in which you want to suppress the warning:

   @org.netbeans.api.annotations.common.SuppressWarnings(value="your_warning_id", justification="Explanation why this is false warning")

4. It is good to be consistent when justifying the same type of things.

Additional information

• The SignatureTest also helps to maintain high quality of NetBeans code.

• This page was last modified on 30 January 2013, at 15:14.
• This page has been accessed 9,628 times.