-
Notifications
You must be signed in to change notification settings - Fork 45
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.
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.
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.
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.
Normally interested developers do contribute crypto plug-ins. The official JCrypTool Plug-ins in this category always start with org.jcryptool. The following list shows the complete names of all existing categories today.
- Analysis: org.jcryptool.analysis
- Classic Algorithms: org.jcryptool.crypto.classic
- Modern Algorithms: org.jcryptool.crypto.modern
- FlexiProvider Algorithms: org.jcryptool.crypto.flexiprovider
- Games: org.jcryptool.games
- Visualizations: org.jcryptool.visual
The categories name reflects in the so called branding plug-in. This plug-in takes care of the branding of all plug-ins in this category and can contain general code used by one or more plug-ins. The feature of a category can be identified by adding .feature to the name of the branding plug-in.
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.
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.
We are an international project, all code (classes, methods, variables and so on) and all Javadoc have to be written in English.
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.
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.
Stick to the Eclipse Development Conventions and Guidelines.
Need help? Please visit the public JCT Chatroom or open a new Issue and ask your question. We'll be happy to assist you!