Configuring Your Environment for ZipTie Development

This page contains the recommended configurations for developers working with the ZipTie codebase with an eye towards contribution. You can download all configuration import files from the attachments at the bottom of this page, or download them from each section discussed below.

Step 1: Get the Source

HowtoCvs

Step 2: Set target platform

Go to Window->Preferences->Plug-in Development->Target Platform and change the Location to point at workspace/TargetPlatform/eclipse

• set the target platform:
  

http://www.ziptie.org/node/274

Step 3: Code Style Settings (required)

The ZipTie team uses specific code style setting in Eclipse to format our code. Formatting with this template should result in a file that is compliant with the ZipTie Coding Standard as well as complying with the enforcement rules of Checkstyle. All files should be formatted with these settings (Shift-Ctrl-F in Eclipse).

The import file for the coding style is located in the Build project in the /conf directory.

Step 4: Code Template (required)

The ZipTie team uses the following code template. It ensures that all files have the appropriate Mozilla Public License (MPL 1.1) banner at the top, as well as other minor formatting tweaks.

The import file for the coding template is located in the Build project in the /conf directory.

Step 5: eclipse-cs (required)

This is the Eclipse plugin for the Checkstyle project, and provides enforcement of our code style settings as well as the ZipTie Coding Standard.

eclipse_cs update site: http://eclipse-cs.sourceforge.net/update

After installing the plugins, follow these instructions to configure:

Select "New..."

Choose "Project Relative Configuration..."

Pick the configuration from the Build project.

You can enable/disable on a project-by-project basis.

Tips for Complying with Checkstyle (you should read these)

• If a method overrides a parent's method, you should remove whatever comment it has. Then position your cursor on the method name and press CTRL-ALT-J to automatically add the appropriate comment. It will add a comment like this: /** {@inheritDoc} */
• Empty blocks are not allowed. In almost every case you can: 'continue' or 'break' if in a loop, 'return', or log something. If you can't do any of these, think about restructuring the code. If you still can't eliminate it, let me know (mailto:brett@ziptie.org).
• We have the following maximums set:
  • Line length: 160 characters
  • File length: 2000 lines
  • Method length: 160 lines (if it's longer than this, you should refactor the code. we will entertain raising this to 180 lines)
  • Max parameters: 7
• See this link if you can't figure out the error/warning: http://checkstyle.sourceforge.net/config.html#Modules
• JavaDoc is required on all public methods. Use CTRL-ALT-J on the method name to get the best boiler-plate to work from.
• The "Magic Number" warning can perhaps be the most annoying to deal with. This occurs when you use something like "23" or "1000" in a method. Sometimes the reader of the code can't understand where the value came from or what it means (sometimes they can). The fix for this is to define a constant (select the number, right-click -> Refactor -> Extract Constant). In this case, probably DEFAULT_TELNET_PORT = 23, and ONE_SECOND = 1000 (or maybe TIMEOUT_MILLIS = 1000).

Step 6: FindBugs (required)

The ZipTie development team uses the FindBugs plugin.

FindBugs Eclipse update site: http://findbugs.cs.umd.edu/eclipse

Step 7: Metrics (optional)

The ZipTie development team has started using the Metrics plugin. We are experimenting with this tool and do not currently have guidelines about its use. Use it to inform your development, but feel free to ignore some of it's warnings. Additionally, this is a plugin that you should Disable (in the project settings) when you're not looking for it's advice -- it is very expensive to run. You will need to clean build after Enabling it.

Metrics Plugin: http://sourceforge.net/projects/metrics

Unfortunately, this tool does not provide for import/export of settings so here are our recommendations:

Metrics Preferences -> Safe Ranges

Metric	Max	Comment
Number of Static Methods	20	max # of static methods in a class
Total Lines of Code	?	max lines of code in a package
Afferent Coupling	?	see below
Normalized Distance	?	see below
Number of Classes	25	max # of classes per package
Specialization Index	?	see below
Instability	?	see below
Number of Attributes	10	max # of attributes per class
Number of Packages	?	max # of packages referenced by a class?
Method Lines of Code	120	max lines of code in a method
Weighted methods per Class	?
Number of Overridden Methods	?	see below
Number of static Attributes	?	max # of static attributes per class
Nested Block Depth	5	max block nesting level
Number of methods	?	max # of methods per class
Lack of Cohesion of Methods	?	see below
McCabe? Cyclomatic Complexity	10	see below
Number of Parameters	5	max # of input parameters per method
Abstractness	?	see below
Number of Interfaces	2	max # of interfaces a class can implement?
Efferent Coupling	?	see below
Number of Children	8	max # of subclasses from a parent class
Depth of Inheritance Tree	6	max levels of class or interface inheritance

Some of these metrics, in this author's opinion, are fairly meaningless at worst or hard to quantify a "good" range for at best.

See this link for a discussion of the metrics: http://open.ncsu.edu/se/tutorials/metrics/index.html#section4_0