Code Style

Introduction

We follow the Google Java Style Guide for our Java code with some small adaptation (see below). In other code, e.g. JavaScript or SQL, we also stay close to this basic style with some exceptions and additions, see sections on the specific languages below.

Summary

Here is a brief summary of the most important points from the Google Java Style Guide:

General

• Spaces, not tabs
• No wildcard imports
• Column limit 100

Braces

• Always use braces, even when optional
• Use Egyptian brackets

Misc

• Always use @Override

• Use capital L in long literals

• Pay attention to the correct order of modifiers:

  public protected private abstract default static final transient volatile synchronized

Vertical whitespace

• Must use one blank line between methods
• Can use blank line(s) to group fields
• Can use blank lines(s) to group statements
• Note: Don't use more than two consecutive blank lines

Horizontal whitespace

• Use a space between keywords and braces and before opening braces
• Use a space around binary or ternary operators
• After ,:; (unless it's a trailing space)

Additional rules

Only include fields and methods that are necessary. Each class should be structured the following way:

1. logger (private static final Logger log)
2. private constants (private static final)
3. public constants (public static final)
4. fields (in some logical order/grouping)
5. all constructor(s)
6. getters/setters/overrides/other methods
   • in some logical order
   • keep getters and setters together
   • keep related methods together
   • keep private helper methods close to the method(s) that use it (preferably below)
   • overloads should never be split
7. equals, hashCode, toString methods

Other languages

Unless otherwise noted, please follow the parts of the java style guide that make sense in the other languages (most notably whitespace conventions).

SQL

• Use single quotes for strings

Conventions

There are also a few coding conventions to ensure predictability.

Method names for DAOs and clients

Methods that retrieve an object are generally prefixed with get. Do not include parameters names in the method name, unless the type of a parameter is ambiguous and a different name is necessary to distinguish two overloaded methods (e.g. getByProposalId(long) and getByContestId(long)).

Method parameter order

In general, parameter order should be consistent across the system as much as possible. Related methods should always have their parameters in the same order.

A few guidelines:

• Parameters that belong together should be logically grouped together, e.g. activityCategory, categoryId, userId
• Grouped parameters should be in ascending order according to specificity (get more specific from left to right), e.g. activityCategory, categoryId

Handler methods

A handler method inside a Spring MVC controller should follow the following order for parameters. Parameters that are not required should be skipped and additional parameters can be added at the end.

@GetMapping("/contests/{contestYear}/{contestUrlName}")
public String showContestProposals(
        // start with servlet and mvc objects injected by Spring MVC
        HttpServletRequest request,
        HttpServletResponse response,
        Model model,
        // continue with objects injected via custom resolvers
        Member loggedInMember,
        ProposalContext proposalContext,
        // followed by path variables and request parameters
        @PathVariable String contestYear,
        @PathVariable String contestUrlName,
        @RequestParam(required = false) long phaseId,
        // lastly, add model attributes and the binding result
        @Valid SortFilterPage sortFilterPage,
        BindingResult bindingResult) {

    // controller code
    return "viewName";
}

Other information and tools

IDE settings

The repository has a .editorconfig with indentation settings that should be supported by most IDEs. If you are using IntelliJ IDEA, the config files in the .idea directory should already configure the defaults correctly to adhere to the code style by default. You can reformat code in a file by pressing cmd + alt + L. Be mindful of what you reformat and note that the code style purposely leaves some leeway in how exactly the files is formatted to let the developer decide what is the most readable version allowed within the code style.