# Coding Guidelines

## Backend

We complie with the [Google-Java-Guidelines](https://google.github.io/styleguide/javaguide.html), we will summarize the most important aspects in this document as well as some further recommendations.

### File and Package Structure

A source file consists of, in order:

1. License or copyright information, if present
2. Package statement
3. Import statements
4. Exactly one top-level class

Respect the packages in the project (layer-seperation):

- **package endpoint**: contains all REST-Endpoints
- *subpackage DTO*: contains all DTOs
- *subpackage Mapper*: contains all Mappers
- **package service**: contains all services - top level only interfaces
- *subpackage Implementation*: contains all implementations
- **package persistence**: contains all persistence relevant classes
- *subpackage Repository*: contains all repositories for all entities
- *subpackage Entity*: contains all entities of the project
- **package validator**: contains all custom validators
- **package config**: contains all config-beans, e.g. all classes annotated with @Config
- **package security**: contains all security relevant configurations

The Test project should have the same structures, if given.

### Source File structure:

Each `.java` source file should have the following ordering (from top of the file to bottom):

- Package declaration
- Import declaration (only import necessary functionality, not always wildcard imports)
- Constructutors
- Public Methods
- Package-Private/Protected Methods
- Private Methods

Each overriden Method shall be annotated with `@Override`.

### Formatting

#### Braces
Braces are used with `if, else, for, do` and `while` statements, even when the body is empty or contains only a single statement.

We follow the K&R bracing style:

Braces follow the Kernighan and Ritchie style ("Egyptian brackets") for nonempty blocks and block-like constructs:

- No line break before the opening brace, except as detailed below.
- Line break after the opening brace.
- Line break before the closing brace.
- Line break after the closing brace, only if that brace terminates a statement or terminates the body of a method, constructor, or named class. For example, there is no line break after the brace if it is followed by else or a comma.
(Standard in IntelliJ's format Settings)

return () -> {
  while (condition()) {
    method();
  }
};

return new MyClass() {
    @Override 
    public void method() {
        if (condition()) {
          try {
            something();
          } catch (ProblemException e) {
            recover();
          }
        } else {
          lastThing();
        }
    }
};

#### General
- Empty blocks: may be concise
- Block indentation: +2 spaces
- One statement per line
- Brake lines only by dot-operator, two-columns, a pipe in complex expressions.
- Between consecutive members or initializers of a class: fields, constructors, methods, nested classes, static initializers, and instance initializers.
- One line seperation between code-blocks
- Switch statements always have to have a valid default branch

#### Variables

- One variable per declaration, e.g.,

int a,b;

is forbidden.

- No C-style array declarations

#### Annotations
- All annotations must be explicit (e.g., no implicit `@Autowired`)
- Annotations must always be above the corresponding statement

### Comments & Documentation

- Multi-line comments must be written in `/* */` Notation, so

// i
// am
// a 
// comment

is not allowed.

- Java docs must be written at least on every interface (or on a concrete class, if it does not implement an interface)
- Java-Docs must always describe return-values, parameters, exceptions and functionality
- Java-Docs must use tags, e.g. `@param, @return` etc.

### Naming conventions

- Source file sames names only letters and digits in camelCase. (except `.xml, .yml, .properties` and `.json` files)
- Class names only letters and digits in camelcase and always start with an uppercase letter.
- Variable and method names only letters and digits in camelCase. And always start with a lowercase letter
- Constant names must be written in upper-snake-case (e.g. CONST_VALUE)

#### Interfaces
- Each Service, Persistance must implement an interface to exploit layer-seperation.
#### Endpoint
- Starts with the entity name the endpoint refers to
- Ends with "Endpoint"
- e.g. `HorseEndpoint`
#### Service
- Starts with the entity name the service refers to
- Ends with "Service"
- e.g. `HorseService`
#### Persistance
- Starts with the entity name the repository refers to
- Ends with "Repository"
- e.g. `HorseRepository`
#### Dto
- Starts with the entity name the dto refers to
- End with "Dto"
- e.g. `HorseDto`
#### Entity
- e.g. `Horse`
#### Mapper
- Starts with the entity name the dto refers to
- End with "Mapper"
- e.g. `HorseMapper`

### Programming Practices

#### Exceptions

- Never ignore exceptions in a catch clause, e.g.:

try {
  int i = Integer.parseInt(response);
  return handleNumericResponse(i);
} catch (NumberFormatException ok) {
  // it's not numeric; that's fine, just continue
}

- Always catch the most specific exception (so no `catch Exception e`).

- Always free resources in a `finally` block.

#### Logging

- Every Method must be logged.
- The log-level depends on the specific case:
- In an endpoint use INFO to log an ingoing request
- In all other cases use DEBUG to logg methods

- Use WARN or ERROR to log exceptions
- Do not use string concatination in logger calls.

#### REST

All endpoints must be REST-conform.
See [Little Book of REST Services](https://www.kennethlange.com/books/The-Little-Book-on-REST-Services.pdf) for more details.

## Frontend

Since Angular itself suggest a sophisticated coding-guideline, we complie with it [Angular Coding Guidelines](https://angular.io/guide/styleguide)