Good Practices for Enterprise Java Solutions

good practices

Good Practices for Enterprise Java Solutions

Here are some good practices for developing enterprise Modern Java solutions.

development-good-practices-mindmap

Bounded Domain Development

Extendable Bounded Domain Models

Identifiers
Names
Codes
Tags
Comments

To be written

The approach improved over time and is now based on the following principles:

Immutable entities
Mutable entities

==== Audit Event Conventions

The event field is one of the following values

import

Any entity imported from an external source is audited.

export

Any entity exported to an external source is audited.

create

Each time a file is generated and exported shall be audited. For example, the creation of an invoice document is audited.

login

Login of a user.

logout

Logout of a user.

The component field has the structure net.tangly.component_name. The component field is the Java module name of the design component.

All import and export operations should be audited. An import happens each time the system reads data from an external system. An export happens each time the system sends data to an external system.

Java Conventions

Modern Java Constructs

Use modern Java constructs in our daily coding

  • Prefer a record over a class abstraction to promote immutable objects.

  • Prefer stream approach over explicit control statements to promote functional programming.

  • Avoid returning a null value. Return either an optional or an empty collection.

  • Return immutable collections.

  • Parameters are per default non-null. Use the @Nullable annotation to mark nullable parameters.

  • Promote modules for information hiding and reducing coupling between components.

  • Use var construct to have more legible code [1].

String toString() Method

The method implementation uses a String.format() approach. We assume that Java will introduce intrinsic support for an efficient implementation of toString method based on String.format(). As soon as the intrinsics is available, we will migrate to the supported version as stated in JEP 348.

The toString method is used to create a detailed audit and logging messages and support production error searching. The format of the message is based on the build-in format defined in the JDK for Java records.

    @Override
    public String toString() {
        return String.format("created=%s, author=%s, text=%s, tags=%s",
            created(), author(), text(), Tag.text(tags));
    }

boolean equals(Object) Method

The extended instanceof operator allows a compact and legible definition of the equality method. The whole method body is written as one statement.

    @Override
    public boolean equals(Object obj) {
        return (obj instanceof Comment o) && Objects.equals(created(), o.created())
            && Objects.equals(author(), o.author()) && Objects.equals(text(), o.text())
            && Objects.equals(tags(), o.tags());
    }

Design Conventions

Use plantUML and Mermaid to document all major design decisions with diagrams. Diagrams shall be defined to explain specific aspects of a component. Do not try to model the whole source code.

Knowledge Database

  1. How should you document your design?

    Document your design information with Asciidoc. Diagrams are created with plantUML and Mermaid. The documentation is stored in the source code repository and published as a static project website.

  2. How should you document your code?

    Please use the clean code principles and document your code with JavaDoc. The JavaDoc shall be integrated into the static website project documentation. Intellij IDEA IDE has a nice integration with JavaDoc.

  3. How should you build your application?

    Use Gradle Build Tool as the build tool. The build tool has a nice integration with Git. Our preferred continuous integration tool is GitHub.

  4. How should you develop source code?

    Use IntelliJ IDEA IDE for development. The IDE has a nice integration with Gradle Build Tool and Git.

Links

1. Upon using the var construct for a few years, we are convinced the resulting code is more legible and compact.