Contributing to the JavaCC Eclipse Plug-in

This document aims at telling you what you need to know if you want to contribute to the plug-in.

History

Created 02-03/2021. 1.6.0.
Updated 07/2023. 1.6.0. Following restructurations.

Starting

Get the source from GIT on SourceForge.

There are 6 projects / plug-ins:

The term plug-in generally means the JavaCC Eclipse plug-in which in fact is made of 3 Eclipse bundles (Core, UI, Help).

Get the second one sf.eclipse.javacc.ui. Make a modification and test it: for example:

• open in sf.eclipse.javacc.ui.action.Format.java
• add 2 lines after public void run(IAction action) {:
  • IWorkbenchWindow w = PlatformUI.getWorkbench().getActiveWorkbenchWindow();
  • MessageDialog.openInformation(w.getShell()," My Contribution "," Format action");
• open plug-in.xml and on the Overview tab click Launch an Eclipse application
• if you want to launch the Eclipse application with regional settings different than your workstation's ones, add -nl <locale> ( like -nl en_EN) in the Program arguments of the Arguments tab of the launch configuration
• now test on a .jj file the format command, you should see a Message window " My Contribution ".

Now that you have a plug-in ready to improve, below are some topics for contributions, some settings information to know and some coding standards to follow, and then more insights on how the plug-in is designed...

Areas for contributions

Of course any good idea will be discussed. Here are some needs:

1. create bundles for other languages than english and french (easy, only needs good translations)
2. create test suites for automating the plug-in functional validation: JUnit, GUI... Integration with a code coverage tool like EclMEmma / JaCoCo would be a plus
3. create test infrastructure for automating the plug-in technical validation (on different Eclipse / JDK / JavaCC / JTB versions & platforms)
4. add the ability to drop language code support (for people who want to use a JavaCC version like 8.x which transparently handles the code blocks)
5. integrate / extend the JDT (currently the plug-in handles Java code without using the JDT)
6. integrate / extend the CDT (currently the plug-in does not handle C++ code)
7. use the internal parser for formating, text styling, matching pairs, content assisting, instead of the current scanners and finite state machine
8. update the plug-in with Java 1.7+ grammars (currently the plug-in is limited to Java 1.5 syntax) (will be much more simple if the previous item is done)
9. add a refactoring feature (rename / move, at both the JavaCC and the Java levels)

Common settings, coding standards

Project properties

The 6 Eclipse projects are defined to be of UTF-8 encoding, with Inherited from container new text file line delimiter (properties stored in .settings/org.eclipse.core.resources.prefs).

On a Unix workstation, you may first have to run the File/Convert Line delimiters to/Unix command on the entire project. Then before committing, please run the File/Convert Line delimiters to/Windows.

Eclipse tools settings

As a general rule, all rules should be set no less than the Warning level, and NO warning should be left before committing!.
Why? Because if some aspect is thought (by the tools designers) to be a potential issue, then it should be tracked (by us, setting it with a warning), and any occurrence of this aspect in our code should be resolved, that is to say we have to fix it and make the occurrence disappear.

Code style, cleanup and save actions should also be strictly followed.
Why? To get homogeneous code. Eclipse makes this easy, so we use it!

All this is configured through Project/Properties and stored in the .settings files:

• Java Code Style (in .settings/org.eclipse.jdt.ui.prefs)
  • Clean Up (active profile in .settings/mma_cleanup_2.xml)
  • Formatter (active profile in .settings/mma_formatter_3.xml)
  • Organize Imports
• Java compiler (in .settings/org.eclipse.jdt.core.prefs)
  • Build
  • Errors/warnings
  • Javadoc
• Plug-in Development (in .settings/org.eclipse.pde.prefs)

You should get all these settings automatically when checking out the .settings files, and you should not modify these settings, even more commit them.

Comments and Javadoc

This plug-in has very few contributors, only one maintainer, on a very small part time.
So people will look at the code many years after it has being developed and tested, and will not remember a lot about it.
Experience shows that documenting the code helps people remember back the logic, the rationales, the big and little issues; so that is why detailed comments are required, to speed up the time required to put one's head in the code.
Eclipse plug-in development is not easy, as user guides, tutorials, presentations exist to some extend but are disseminated over many sites, articles... So just referencing the resources that have been used while developing will be a mega plus. Also full Javadoc comments are required because they are extensively used in Eclipse by just hovering above a field, parameter or variable.
The common geek attitude 'I write auto-documented code just by the proper naming' is not found very useful on this kind of project. 20+ years of experience in auditing small and big software products has shown that this leads to products with number of defects much over the average.

Specific coding aspects

Getters and setters, visibility modifiers

I believe that Getters and setters are a serious flaw of Java/J2E developments.
Yes. Why? Because

• I find the common "members encapsulation" rationale to be weak, as proper controlled access done with the public / protected / 'package' / private modifiers is most of the time enough.
• Developers have named getXxxx() / setXxxx() any method performing logic for computing / retrieving / storing data, so real getters and setters cannot be guessed by the method names.
• Developers took the habit to copy/paste getXxxx().getYyyy()...getZzzzz() in the code, without memorizing the results, therefore producing code that calls thousands or millions of times the same methods, leading to horrible performances...

So use getters and setters only when really need, ie:

• Eclipse methods that must be overriden
• Access from other packages

but not when the member has to be accessed within the inner classes or the package classes (ie use directly the member with the proper modifier).

Final modifier

It is recommended to use the final modifier everywhere when possible (you will see this in the tools settings).
Why? Because it helps javac and the JVM perform code elimination and JIT compilation.
And specially on methods (the common argument against it is that it does not allow any - unknown - body to override them once in the future, but this plug-in is not in this case, no people other than the few maintainers will ever feel the need to override one of its method).

Strings, constants, NLS

A lot of effort is spent on centralizing string constants in a few classes (and are static imported in the other classes).
A lot of effort is spent internationalizing strings used in the UI, and tagging the others as NON-NLS.
Currently only 2 bundles are provided, the english one (EN), and the french one (FR). Others are welcomed!

Performance coding rules

15+ years of profiling on numerous projects have shown common repeated performance issues.
A big category can be summarized as small streams make great rivers, where issues are on:

• lists and maps initial allocations: always try to compute the final size of a structure, and create it with the appropriate corresponding initial allocation
• string concatenation: for concatenations of 3 or more strings, use a StringBuilder, with the appropriate target size, and use append(); exceptions are accepted on infrequently called methods (exceptions, logs, ...)
• reuse lists, maps, arrays, buffers (clearing the contents) instead of creating new ones

All these reduce object initial or intermediate allocations and therefore subsequent CPU and garbage collection activity.

Other (obvious) recommendations are to memorize intermediate results, and outside the loops if possible.

Code quality checking

It is recommended to run UCDetector on the code and follow the advices. UCDetector, "an Unused Code Detector", helps finding the potential static and final uses, as well as the right visibility modifiers.
It is available as an Eclipse plugin on the MarketPlace.

It is recommended to run STAN on the code, use the metrics to improve its quality, and remove the tangles. STAN, "a STructure ANalysis tool", helps visualize the packages and classes design, measure the common code quality metrics, and see the design flaws, especially the tangles (subgraphs where at least two nodes where each node is reachable from each other).
It is available as an Eclipse plugin on the MarketPlace. The JavaCC plug-in is small enough to be processed by STAN without a commercial license.

Projects descriptions

See Projects descriptions.

Note that in previous versions 1.5.x the projects were different (site projects were named -web, core & ui were mixed in javacc, and javacc.headless had the headless package of core.