Reply

Project Compiler Restrictions

At 11:10 PM on Feb 26, 2006, R.J. Lorimer wrote:

Recently on the general discussion list for Eclipse, a reminder was sent out to all of the feature teams for Eclipse to bring their optional compiler settings up to the minimum requirements of the release engineering team (RelEng - the team who does the actual builds of the Eclipse platform). Basically, the release engineering team builds with certain criteria in mind, and it's important for each plug-in owner to ensure they build to at least that level of quality to minimize the opportunity for errors and warnings during the major integration builds of Eclipse. Philippe Mulet, a committer on the JDT core team, sent the email out with a list of the JDT Core teams project-settings.

One of the things that this brings to the surface is that if you are using Eclipse as your development environment for your project, you shouldn't be afraid to enable some off-by-default features of the Eclipse compiler to help increase code-quality and help enforce coding conventions as you see fit.

Eclipse 3.1 introduced the ability to supply settings for the compiler (among other things) that are specific to your project. Eclipse will store them in the project folder under the .settings folder, and this allows you to share a certain compiler set up with your team (just like you would the classpath and project file).

To enable project-specific settings for the compiler, go into your project's preferences, and then navigate to the Java Compiler[+]->Errors and Warnings category:

You'll see that there is a checkbox available for 'Enable Project-Specific Settings'. Check this on to start customizing these settings.

Some of the optional settings are interesting. Let's run through a few of them (note that which settings are off-by-default at the time of this writing is true for 3.2 Milestone 5 (and most likely 3.2 final).

Code Style

• Indirect access to static member - Note that this is not the same as 'non-static access to static member'. This would be for cases where a constant is defined on a superclass (ClassA) and you reference it using the subclass (ClassB - e.g. ClassB.CONSTANT_REF)
• Unqualified access to instance field - Turning this check on would require that you use the this keyword for any reference to an instance variable.
• Undocumented empty block - Any block (method, if statement, while statement, etc) that is empty and doesn't have a corresponding comment (the comment must be inside the block) will be flagged as needing to be commented. In other words, an empty method is allowed to have a comment like '// TODO - not implemented yet' or '// no-operation', but it can't just be empty.
• Access to a non-accessible member of an enclosing type - Anyone want to fill me in on what this one means? I honestly don't know...
• Parameter assignment - It's typically considered bad form to assign new values to a method/constructor parameter; this check ensures that parameters aren't assigned.
• Non-externalized strings (missing/unused $NON-NLS$ tag)

Potential programming problems

• Serializable class without serialVersionUID - Some of you may be thinking that this one is actually on; and you'd be right in reference to 3.1 and early 3.2 milestone releases. It is now off-by-default, but if you like this kind of thing, you can turn it back on.
• Possible accidental boolean assignment (e.g. if (a = b)) - Common problem if you miss an '=' operator on a boolean assignment.
• Empty statement - This will flag cases where you use the rarely used empty control-flow statement, such as if(...); or while(...); .
• Boxing and unboxing conversions - This flags any location where you use auto-(un)boxing. If you don't like this Java 5 feature (which some don't), this is a good way to ensure you don't use it, or at least that you're aware of it.
• Enum type constant not covered on 'switch' - In Java 5 it is possible to switch over a set of enumerations; if you don't have every possible enumeration covered by your switch cases, this line will flag it.
• Switch case fall through - This catches places where a break is not placed properly after a case in a switch statement. While using switch-case fall-through is
• Field declaration hides another field or variable - This isn't terribly common, but is possible in a few cases, such as if a protected super-class is over-shadowed by a subclass field, or an inner-class variable over-shadows an outer-class variable.
• Local variable declaration hides another field or variable - Flags any scenario where a local variable's name will collide with a field name, and in turn will hide the field. There is also an optional checkbox to include this check on constructor and 'setter' parameters; a lot of times developers like to use the same name intentionally on constructors and setters so you have this kind of convention: this.name = name; . Other developers, on the other hand, prefer to use a naming convention to prevent name collisions, even in this case (e.g. this.name = newName; ).

Unnecessary code

• Parameter is never read - Checks to see if any parameters to the method are not actually used by the method. This ensures that methods are no more complicated than need be. The most common case where you might actually want parameters to betest passed in but might not actually want to use them is when you are fulfilling a contract via implementing an interface or overriding in a subclass; there is an additional checkbox you can leave unchecked to ensure that these scenarios (override and implement) aren't considered errors by the compiler.
• Unnecessary else statement - This will catch scenarios where an else statement is unnecessary because successful completion of the corresponding 'if' statement(s) would have cause the execution to leave the method (in other words, the 'if' statement ends with a 'throws' or 'returns' clause).
• Unnecessary cast or 'instanceof' operation - Fairly self explanatory; if you can perform all of the operations without casting, or if you perform an instanceof check that is unnecessary (such as ArrayList instanceof List ), this setting will flag that.
• Unnecessary declaration of thrown checked exception - This allows you to flag when you throw a checked exception of a certain type, even though it isn't possible for the internal code of the method to throw that particular checked exception. There is an additional flag to also mark these cases on methods that override or implement a contract on a super-class or interface.

Generic types

• Usage of raw type - Fairly self explanatory; basically any code will be flagged that uses a type that supports generics but the reference is raw (meaning no generics parameters defined).

Annotations

• Missing '@Override' annotation - As can probably be gathered, this catches any places where a method is overridden but it hasn't been declared (via the override annotation) to be overridden.
• Missing '@Deprecated' annotation - Any place where you have used the '@deprecated' Javadoc tag but haven't used the Java 5 '@Deprecated' annotation will be flagged by this property.

In addition, in the Javadoc category of the project preference page, you can set up some optional Javadoc rules:

• Malformed Javadoc comments - This will report locations where Javadoc comments are in the wrong order, or have markup in them that is invalid according to the Javadoc tools specification. This setting can be trimmed down to only concern Javadoc for members of at least a certain visibility (public, protected, default, and private). Various sub-settings can be enabled or disabled including errors in tags, non-visible references, and deprecated references.
• Missing Javadoc tags - This captures when certain tags of a Javadoc are missing that should be supplied. As before, this setting can be controlled for only certain visibility members. In addition, it can consider overridden or implemented methods separately.
• Missing Javadoc comments - This captures when the Javadoc is missing altogether. As before, this setting can be controlled for only certain visibility members. In addition, it can consider overridden or implemented methods separately.

Of course, if these settings aren't enough, you can go get the PMD plug-in , the Checkstyle plug-in , or even try out the Test and Performance Tools Platform Static Analysis Tools (part of the TPTP plug-in) which is just now for Callisto receiving a set of default rules; and looks to be (at some point) Eclipse's standard static-analysis platform.

Until next time,

R.J. Lorimer
Contributing Editor - rj -at- javalobby.org
Author              - http://www.coffee-bytes.com
Software Consultant - http://www.numbersix.com

0 replies so far ( Post your own)