Page tree
Skip to end of metadata
Go to start of metadata

Your Rating: Results: 1 Star2 Star3 Star4 Star5 Star 133 rates

Java

General Style

Order of methods

We aim for best readability - that's we (from now on) put methods is a specific order:

  • technical/config methods first (e.g. getters, setters, add-methods for collections, ...) - business methods last
  • methods that logically belong together should be grouped (e.g. if there's 2 constructors they should be placed next to each other)

Imports

  • We use the following order
    • static imports
    • all "other" (e.g. info.*) (warning) it would seem the Eclipse file we currently provide is not up to date with this (in particular, it does have a "other" rule, it only has one for info.magnolia.*)
    • java, javax, org, com
  • .* Imports are only allowed for static ones (checked by our checkstyle setting)
    • configure your IDE to use 2 as Number of static imports needed for .* (e.g. in Eclipse Preferences -> Java -> Codestyle -> Organize Imports)

Indentation

  • Tab policy: spaces only (warning)
  • Indentation: 4 spaces for Java-Files, 2 spaces for XML
  • No maximum line width, no automated line wrap

Naming

  • We preferably don't use abbreviations in classnames (only exception to that rule is MgnlSomething)
  • See Naming conventions
  • Enums: despite enums being constants, we make an exception: lowercase/camelCase enum members are perfectly acceptable. Two reasons:
    • They can be used in configuration (tree), where an ALL_CAPITAL value would look out of place,
    • They can implement complex types, whereas "regular" constants are usually native types or Strings. It's not unusual to do stuff like layout.doLayout(someComponent), where layout is actually one of the values of MyLayoutEnum. It reads nicer without the capitals and underscores.

If-statements

  • Single-line if-statements: we always use curly braces
  • Unnecessary else-branch: if the else is not necessary (e.g. because if-branch always returns or throws an exception) we omit it

Functional-style idioms

  • Streams/Optionals are formatted one operation per line, after the .stream() initiator;
    • actually can be considered a general recommendation for fluent APIs
    • static imports for Collectors is highly encouraged
  • Streams are generally preferred to Guava transforms
  • Optional is a good return type, not an argument type
Optional<VirtualUriMapping.Result> mappingBestMatch = registry.getAllDefinitions().stream()
        .map(uriMapping -> uriMapping.mapUri(uri))
        .filter(Optional::isPresent)
        .map(Optional::get)
        .max(VirtualUriMapping.Result::compareTo);


Overrides

  • for optimal refactoring support we use the @Override for all methods that override methods declared in superclasses/implemented interfaces
    • Hint: you might want to adapt compiler settings of your IDE to show Errors on missing @Override's (Eclipse and Idea provide that option)

SuppressWarnings

  • we try to avoid using @SuppressWarnings
    • if it's required, make sure you use it for the smallest scope - e.g. don't add on method level when you only need it for one instruction
      • example: HttpServletRequest#getHeaderNames() returns Enumeration instead of Enumeration<String>
        • -> here you could use @SuppressWarnings("unchecked") just before lines like: Enumeration<String> myHeaderNames = myHttpServletRequest.getHeaderNames();
  • we don't use @SuppressWarnings("deprecation")
    • using deprecated code is a smell - we wan't to be aware of places where we use old stuff
    • try to replace the deprecated code with it's replacement

serialVersionUID's

We don't explicitly set serialVersionUID's as we don't want to decide ourselves when these id's should be updated. We rely on the JVM doing that for us (being aware that this id's could potentially differ from JVM to JVM). If for any (valid) reason, such an id would be needed for a given class, the reason needs to be documented in the code. Failing that, there's a good chance the field will be removed by a fellow zealous developer.

$NON-NLS-1$

  • if you come across a //$NON-NLS-1$ please just delete it - that's legacy stuff created by Eclipse - we don't want to keep that!

TODOs & FIXMEs

  • these are used for minor issues or hints. As it might be handy to ask the author for details and we don't want to spend too much time on querying the SCM, it's now mandatory to add the author's name:
    • e.g. TODO dlipp - tell the world we'll now always add authors to the TODOs and FIXMEs

Eclipse setup

Please see Eclipse setup page and attached formatter settings (Magnolia.epf).

Intellij setup

Please see Intellij IDEA page and attached formatter settings (Magnolia-IntelliJ-CodeStyle.xml).

Lombok

We use Lombok sparingly in our own implementation details; we try to avoid abusing it for publicly visible code (configured classes).

  • @EqualsAndHashCode are mostly fine
  • @Getter@Setter should be avoided in classes which are not plain stupid POJOs
  • @SneakyThrows should be avoided in best effort

YAML & Magnolia definitions

YAML is a highly-prominent part of Magnolia configuration; we recommend the following throughout YAML definitions:

  • Put the class property (or fieldType) before any other specific property
    • except for names within sequences
  • Indent sequence values (so they don't appear to be on same level as their parent)
class: info.magnolia.foo.MySmartDefinition
components:
  - name: First component
    class: info.magnolia.foo.MySmartComponent
    description: Some short description of the first component
  - name: Second ...


  • No labels

2 Comments

  1. We actually use two suffixes for types hosting utility methods: "Util" and "Utils". I'd clearly vote for setting "Util" (by far more spread in our codebase) as the standard. It's not common to use plural in type names so why create an exception for Utils?

  2. Our import statement order mandated here makes no sense. (why arbitrary put "org.*" and "com.*" after java and javax packages, but not, say, net.* or lombok.*). Besides, the attached Eclipse configuration doesn't match the description. I propose we follow Google's convention: <our package> (info.magnolia.*), blank, others alphabetically, java, javax.