Background
CloudStack stipulates coding conventions for Java code submitted to the project.
Problem
Converting Java source to this code style is labour intensive. A tool to identify problems would be very useful. A tool to fix them is even better.
Solution
Use CheckStyle in conjunction with Eclipse.
CheckStyle will analyse Java code according to a style file and report any violations. A style file consistent with Apache CloudStack is available for download from the Apache CloudStack wiki.
Eclipse fixes problems and verifies more complex changes. When the CheckStyle Eclipse plugin is installed, problem code is highlighted and an explanation provided on a line by line basis. After updating Eclipse's automatic formatting to meet Apache CloudStack's coding conventions, labour intensive work such as proper indentation is taken care of automagically.
CheckStyle Plugin Install
The CheckStyle Plugin offers an install guide, but the screen shots are for an older version of Eclipse. Think of this an overview rather that step by step instructions.
Eclipse Auto Format
Ctrl-Shft-F will auto format the current file using the current code formatter. However, the default profile is not consistent with ACS coding conventions. By default, Eclipse treats whitespace slightly differently than the Java conventions.
Import new Java Code Style Preferences:
Java Code Style settings are available in the Apache CloudStack repo. Simply import Java Code Style Preferences from .tools\eclipse\eclipse.epf. To do so, open File -> Import, and type "Preferences" into the filter text box.
Update the Code Style Formatter profile:
1. Under Window -> Preferences -> Java -> Code Style -> Formatter, create a new profile based on "Java Conventions". Call it "ACS Java Conventions", and select it as the Active profile.
2. Edit the "ACS Java Conventions".
2.1 Under the "Indentation tab", set tab policy to "Spaces only", 4 characters
2.2 Under "White Space", Arrays -> Array Initializers, turn off 'after opening brace' and turn off 'before closing brace'
3. Confirm changes to close the Profile edit window and the Preferences window.
4. Format your document: Ctrl-Shft-F
CheckStyle Plugin Setup
I do not want to be prescriptive, so just keep the following points in mind:
1. CheckStyle is configured in Project Properties. You'll see a 'CheckStyle' menu in a project's 'Properties' dialog. Source
2. The available styles are configured in teh Checkstyle tab of the Eclipse Preferences (Window->Preferences). Source
3. A custom style file called acs_codestyle.xml was created. This custom checklist is derived from the "Sun Checks" policy that ships with CheckStyle. To get a feel for the differences, export and diff the built-in Sun Checks and the ACS checks.
Final Remarks
Common Errors
Methods marked @Override require final keyword
- Since Java 6, @Override is used to verify that an interface method is being implemented. If method cannot be overriden, you have use the finally keyword to signal this.
Complaints
Magic number warnings make tests less readable
- Non-zero values that appear in methods should be replaced by constants. In Java, constants are static final fields NAMED_IN_ALL_CAPS.
- For unit tests this makes less sense. Test values are often best hidden in the method corresponding to the test rather than being spread out over the test file.
My tests store CloudStack kernel commands in their JSON serialised format. These are very long strings. Keeping them to 80 characters makes them unreadable.
Taking the 'TODO's out removes important metadata
- TODOs are the best way to tell other developers where code needs to be double checked due to gaps in my knowledge.
Edits
- ACS uses 180 max line length, and not 80 chars. I will have to update the style file.
- Eclipse Java Code Style Preferences are available from the Apache CloudStack git repo at ./tools/eclipse/eclipse.epf
No comments :
Post a Comment