Contributing to Lingua Franca

Important

This document contains guidelines specific to this repository. Please also read the general contributing guidelines of the lf-lang organization.

This repository hosts the source code for the Lingua Franca compiler, which is written in Java and Kotlin. We welcome contributions from the community and provide these guidelines in order to make contributing a smooth, efficient, and fun process.

Contributing code

You can work on the Lingua Franca code base in your favorite editor and build using Gradle. We recommend to use the IntelliJ IDE.

Writing tests

An integral part of contributing code is writing tests.

Unit tests for the compiler are located in the org.lflang.tests package (found in the directory core/src/test/java/org/lflang/tests, in the core gradle subproject) and are implemented using the JUnit test framework. These tests are invoked using Gradle. For example, to run all the tests in the org.lflang.tests.compiler package, use the following command:

./gradlew :core:test --tests "org.lflang.tests.compiler.*"

Integration tests consist of complete Lingua Franca programs that are located in the test directory in the root of the repository and are organized first by target, then by category. These tests get indexed automatically and are also invoked using Gradle. For instance, to run all the tests for the C target, use the following command:

./gradlew targetTest -Ptarget=C

For more details, see test/README.md.

Workflow

All code contributions must go through a pull request (PR), pass all tests run in CI, and get an approving review before it is merged. Pushing to the master branch is restricted. All code review is conducted using the Github review system on PRs. Before requesting a code review, ensure that you have:

• applied the [code formatter](code-style-and-formatting);
• [documented](code-style-and-formatting) your code;
• written [tests](writing-tests) that cover your code; and
• accompanied any remaining TODOs or FIXMEs with a link to an active issue.

Code style and formatting

The Lingua Franca compiler is implemented in Java and Kotlin. The overarching advice is to use each language's most widely used idioms and conventions, which are fortunately very similar. Documentation for the code should use Javadoc comments with Markdown formatting for the content. See also documentation generation.

The code base is shipped with a Spotless configuration to check and enforce style compliance. Lingua Franca code (e.g., tests) in this repository is also automatically formatted via Spotless.

Formatting

• To check that modified files are formatted correctly, run:

./gradlew spotlessCheck

• To apply the changes recommended by the formatter, run:

./gradlew spotlessApply

Java code formatting in IntelliJ

Follow the directions here to install the Spotless Gradle plugin. We are not currently aware of a way to run Spotless automatically on file save, but it is possible to configure a keybinding.

There is a plugin specifically for enforcing Google's style guide, but we have found difficulty getting it to work properly.

Lingua Franca code formatting in VS Code

Formatting is provided by the Lingua Franca VS Code extension.

You can enable formatting on save by going to Settings and searching for "format" and checking the box Editor: Format on Save. This can be either a user-level or workspace-level setting.

Checking using Git hooks

If you prefer not to use formatting on save but would still like to avoid committing unformatted code, you can add a file .git/hooks/pre-commit with the contents:

./gradlew spotlessCheck

General guidelines

• Do not copy-paste code. If you want to reuse code, factor it out into a method and call it.
• Keep methods concise. As a rule of thumb, a method should fit on your screen so that it can be read without scrolling. We impose no hard limit on method length, but anything above 40 lines should be considered for breaking up.
• Keep classes concise. Classes should be limited in scope and not become too large. Anything above 1000 lines probably needs refactoring.
• Do not leave FIXMEs. Unaddressed FIXMEs should not be allowed to pass code review unless they are accompanied with a link to a GitHub issue.

Comments

Please adhere to the following principles when writing documentation for your code:

• Write descriptions in English.
• Do not use contractions like "aren't" or "isn't".
• Use imperative in the description of a method, i.e., write "Compute the shortest path," not "Computes the shortest path" (the latter is not a complete sentence).
• In @param JavaDoc tag descriptions it is OK to use incomplete sentences in the interest of brevity.
• Use Markdown formatting.

Java-specific guidelines

We use the Google Java style guide, which leaves a few things unspecified that we discuss here in a bit more depth.

Ordering of class contents (S3.4.2)

The order you choose for the members and initializers of your class can have a great effect on learnability. However, there's no single correct recipe for how to do it; different classes may order their contents in different ways.

What is important is that each class uses some logical order, which its maintainer could explain if asked. For example, new methods are not just habitually added to the end of the class, as that would yield "chronological by date added" ordering, which is not a logical ordering.

When in doubt, the following suggestions might help:

1. Keep all fields at the very top (and sort them internally by visibility).
2. After fields, declare constructors.
3. After constructors, put all methods, in "some logical order".
4. Put inner classes at the very end.

Visibility

Avoid public non-final fields and public collection fields (making them final does not make their contents immutable).

Inheritance

Design for inheritance or prohibit it. Make new classes final by default, and avoid using protected members. The class should only be unsealed if a use case for inheritance shows up, which is in many cases never. Often, composition can offer a better solution than inheritance (also see a blog post on this).

Collections

Use interfaces like List, Set, Map to type variables, constructor parameters, and method signatures, not concrete implementations like LinkedList, HashSet, or LinkedHashMap.

Collection mutability

In Java, instances of collection classes may be read-only. They will throw an exception when modification is attempted. Read-only views on collections are used to prevent external code from modifying an internal collection by accident, which may break class invariants. Encapsulating modifications to the collection into extra mutator methods is good practice, because it allows maintaining class invariants if the class evolves.

• Assume that any list returned from a method of an object that you do not control is unmodifiable unless otherwise documented. That means, make a copy if you need a local modification.
• If you return a collection which is a field of the current object, make it unmodifiable (i.e., return Collections.unmodifiableList(internalList);). If the API must return a modifiable list, then document that it is modifiable. (It's usually better to provide mutator methods to encapsulate the modification to the collection.)

/* Assume the returned list is unmodifiable */
List<String> contents = container.getListOfContents();
/* You can iterate on the list, get an item, but not set/add/remove. To make local modifications, make a copy:*/
contents = new ArrayList<>(contents);
/* Now the list is modifiable, but changes do not affect the `container` object */
contents.add("extra");
 
/* If you need to modify the internal list of the `container`, add a method to the container that encapsulates that logic */
container.add("extra");

Kotlin-specific guidelines

Please follow the Kotlin coding conventions.