Design Conventions

Design conventions for open source components

Design Conventions

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 to document all design decisions with diagrams. Diagrams shall be defined to explain specific aspects of a component. Do not try to model the whole source code.

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