This page provides some development support in the form of howtos. See also High Level Documentation.
We really recommend reading the book Java by Comparison.
Please read https://github.com/cxxr/better-java
- try not to abbreviate names of variables, classes or methods
- use lowerCamelCase instead of snake_case
- name enums in singular, e.g.
Weekdays(except if they represent flags)
We try to build a cleanup mechanism based on formatters. The idea is that we can register these actions in arbitrary places, e.g., onSave, onImport, onExport, cleanup, etc. and apply them to different fields. The formatters themselves are independent of any logic and therefore easy to test.
Drag and Drop makes usage of the Dragboard. For JavaFX the following tutorial is helpful. Note that the data has to be serializable which is put on the dragboard. For drag and drop of Bib-entries between the maintable and the groups panel, a custom Dragboard is used,
CustomLocalDragboard which is a generic alternative to the system one.
For accessing or putting data into the Clipboard use the
BasePanel are the two main classes. You should never directly call them, instead pass them as parameters to the class.
Optional<Path> file = FileHelper.expandFilename(database, fileText, preferences.getFilePreferences());
String path Can be the files name or a relative path to it. The Preferences should only be directly accessed in the GUI. For the usage in logic pass them as parameter
- “fileDirectory” is determined by Globals.pref.get(“userFileDir”) (which defaults to “fileDirectory”
- There is also “fileDirectory-<username>”, which is determined by Globals.prefs.get(“userFileDirIndividual”)
- Used at DatabasePropertiesDialog
logic must not know
ProxyPreferences for encapsulated preferences and https://github.com/JabRef/jabref/pull/658 for a detailed discussion.
See https://github.com/JabRef/jabref/blob/master/src/main/java/org/jabref/logic/preferences/TimestampPreferences.java (via https://github.com/JabRef/jabref/pull/3092) for the current way how to deal with preferences.
Defaults should go into the model package. See Comments in this Commit
Global variables should be avoided. Try to pass them as dependency.
Database.addDatabaseChangeListener does not work as the DatabaseChangedEvent does not provide the field information. Therefore, we have to use BibtexEntry.addPropertyChangeListener(VetoableChangeListener listener)
You can normalize the authors using
org.jabref.model.entry.AuthorList.fixAuthor_firstNameFirst(String). Then the authors always look nice. The only alternative containing all data of the names is
org.jabref.model.entry.AuthorList.fixAuthor_lastNameFirst(String). The other
fix... methods omit data (like the von parts or the junior information).
- Benchmarks can be executed by running the
jmhgradle task (this functionality uses the JMH Gradle plugin)
- Best practices:
- Read test input from
- Return result of calculations (either explicitly or via a
- Read test input from
- List of examples
Try out the YourKit JAva Profiler.
When creating an
equals method follow:
- Use the
==operator to check if the argument is a reference to this object. If so, return
- Use the
instanceofoperator to check if the argument has the correct type. If not, return
- Cast the argument to the correct type.
- For each “significant” field in the class, check if that field of the argument matches the corresponding field of this object. If all these tests succeed, return
- When you are finished writing your equals method, ask yourself three questions: Is it symmetric? Is it transitive? Is it consistent?
- Always override
hashCodewhen you override equals (
hashCodealso has very strict rules) (Item 9 ofEffective Java)
- Don’t try to be too clever
- Don’t substitute another type for
Objectin the equals declaration
Always try to use the methods from the nio-package. For interoperability, they provide methods to convert between file and path. https://docs.oracle.com/javase/tutorial/essential/io/path.html Mapping between old methods and new methods https://docs.oracle.com/javase/tutorial/essential/io/legacy.html#mapping
Table of contents
- Code Quality
- Custom SVG icons
- Error Handling in JabRef
- Event Bus and Event System
- JPackage: Creating a binary and debug it
- Remote Storage
- The LibreOffice Panel
- Testing JabRef
- UI Design Recommendations
- Useful development tooling