Coding Conventions

JCrypTool consists of many different plug-ins, developed by many different people. This inevitably results into many differences in plug-in development. To minimize those differences we do give some conventions and recommendations, which all developers should keep in mind.

To make following our conventions easier we provide the org.jcryptool.core.util plug-in which represents a utility plug-in. You are strongly encouraged to use the functionality provided here in your plug-in.

This small JCrypTool coding conventions guide is a must read for any JCrypTool developer (Core and Crypto). We do not have many rules and conventions, making our documented ones even more important to follow. Any JCrypTool plug-in will be incomplete as long as there are violations against our coding conventions.

Naming Conventions

With regard to the category plug-ins should end with the name of the implementing algorithm or cryptographic procedure, e.g. org.jcryptool.crypto.classic.xor or org.jcryptool.visual.ecdh.

JCrypTool recommends feature usage (Features are used for grouping of plug-ins that do belong together. A feature therefore contains no code at all. Instead it contains only a list of plug-ins (in XML), which lists all plug-ins that belong to the feature, including all required dependencies. So features are mainly used to make installation and maintenance easier for the end user.). However it is possible to only develop plug-ins and to install them separately in JCrypTool. JCrypTool itself is segmented in different features. All feature projects end on .feature and in case of crypto plug-ins do contain the name of the category as well. For example org.jcryptool.crypto.modern.feature.

To use an Update Site for plug-in maintenance you have to use features, never plug-ins. Even in case only one plug-in changed in the whole feature set.

Please use consistent wording in the online help by writing Plug-in (German) and plug-in (English), always with a hyphen.

Fonts, colors and other resources

Every extension point offered by a plug-in can be used (consumed) in your own code. But even outside of extension points, JCrypTool offers various methods and services that should make your development easier and faster. You should especially have a look at the org.jcryptool.core.util plug-in. Besides the described services in the next table, this plug-in offers the interface IConstants, which provides different global constants usable all over JCrypTool. Apart from making the development easier, these methods and services take care of a more unique look & feel of JCrypTool.

Services

The plug-in org.jcryptool.core.util provides lots service classes for an easy access to system fonts and colors. You should use this plug-in instead of implementing your own solution.

CalendarService: Services for date transformations in various other formats.

DirectoryService: Offers access to the user configured home directory, the JCrypTool workspace as well as the default temp directory.

FontService: Offers easy access on used fonts in JCrypTool wizards and views, without requiring to clean up used resources after usage.

ImageService: Provides different default icons and and a simple way for loading own images and icons.

Code Quality

We have three required plug-ins that ensure code quality: Checkstyle, FindBugs and Eclipse ResourceBundle Editor. You are required to use these plug-ins and configure Checkstyle to use the JCrypTool Checkstyle configuration. Plug-in information including setup instructions are available here.

Take these warnings seriously! We are thankful for every donated plug-in, but no developer wants to take over support for a crypto plug-in containing classes with thousands of lines all located in the constructor or one method. Clean Code is what we are looking for (read http://www.amazon.de/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882 by Robert C. Martin in case you have never heard about that).

And format your code with the JCrypTool code formatter before pushing it.

Deprecation Warnings

Don't use any deprecated classes or methods. There are always replacements for these classes, and generally these replacements are highlighted in Javadoc. Using

@SuppressWarnings("deprecation")

in your code is just wrong.

User Interface Layout

The UI framework used in JCrypTool is SWT and JFace. For developers not comfortable with creating a UI solely with Java code the IDE Eclipse provides the WindowBuilder plugin, which does quite a good job at the WYSIWYG approach. However, you will notice soon, that the more complicated your UI gets, the less useful WindowBuilder becomes, as the code parsing gets slow very quickly and it is prone to restructuring the code in a fashion not always comprehensible to the user.

Regardless of how you approach your UI programming, here are some really important guidelines:

No fixed positioning and sizing of UI components. This means, no FormLayout and AbsoluteLayout. It is a well-known source of problems with OS DPI scaling and translations (non-English word being longer than the English one and getting cut-off, e.g.). No rule is without exceptions, but in general, it is a very bad idea to use these kinds of layouts.
If a simple layout manager (e.g. RowLayout) doesn't fit, GridLayout is often the layout manager of choice with which virtually everything can be positioned neatly. A recommended tutorial for the common layout managers is: Understanding Layouts in SWT
With complex UIs, consider splitting your code into modules. Where you would normally create a Composite object and add children to it, you can also create a new class, extending the Composite class, and adding these components in the constructor. When you pass the 1000 lines limit in a View, WizardPage, or Composite implementation, it is probably time to think about where you can off-load UI and Model code into external classes.

Common problems and their solutions:

Stackoverflow SWT tag as a go-to page
"Manual line-breaks" (adding newline characters) in a text field are not necessary, every text widget supports the constructor modifier "SWT.WRAP" and "SWT.MULTI" which adds word-wrapping behavior to it. With GridLayout, the widthHint property of GridData should be set to the width from which the text field should start wrapping words unconditionally.

Language

We are an international project, all code (classes, methods, variables and so on) and all Javadoc have to be written in English.

Logging

Use the JCrypTool logging provided by the org.jcryptool.core.logging plug-in. Using e.printStackTrace(); or System.out.println(); or System.err.println(); in your code is just wrong and the exception will be lost. See here for more information.

Check your Build Configuration

Other than classes new files like images or HTML help files are not automatically included in the plug-in build. In other words: These files will not be available at runtime as long as you don't configure to add them. Open the plug-in's build.properties file and select all files required during runtime.