Documentation Guidelines

Last modified 28 Oct 2021 11:18 +02:00

Architecture and Design

The primary reason of having an Architecture and Design is to guide the development. It is the code that matters at the end of the day and the way how it is deployed. The Architecture and Design section should provide introduction to the midPoint internals, describing how it is structured and how it works. The important goal of the architectural documentation is also description why midPoint looks like this, what options have been considered and why was the current approach chosen. It also provides high-level overview of the implementation.

However, the architectural documentation should not go deep into implementation description. Such a description will quickly get out of sync with the code and is a terrible burden to maintain. We rather focus on keeping the code itself readable and well commented (see below).

The Code is the Best Documentation

The code itself is the best documentation. The documentation that won’t get out of sync with reality. Therefore the first and foremost documentation principle is to keep the code readable. See Java Design and Coding for more details.

Comments in the Code

The implementation that is not obvious from the code should be documented in the code comments. The comments should not describe what is obvious from the code, But the text should describe why it is implemented the way it is implemented. Also point out important details that are not obvious from the code.

BAD

  // Let's iterate over foo objects
  for(Foo f : foos) {
    // Look at all the bars
    if (f.isBar()) {
      // and have a drink
      f.haveADrink();
    }
  }

GOOD

  // Let's have a drink in all the bars in foos list.
  // We need to test all of them, so we can evaluate
  // which was the best one later.
  // The tasting results will be remembered in internal
  // state of Foo objects.
  // Maintain the ordering as the drinks needs to be
  // mixed in correct order ... or else there will be
  // terrible headache next morning.
  for(Foo f : foos) {
    if (f.isBar()) {
      f.haveADrink();
    }
  }

Also use Javadoc a lot. It is almost mandatory of all interfaces and strongly encouraged for all non-trivial methods. Good practice is to start writing a method by writing a short Javadoc description and only then write the code.

Deployment Documentation

The Documentation is focused on IDM engineers deploying midPoint. Deployment documentation should contain installation guides, deployment best practices, configuration reference, documentation of known deployment and engineering issues, etc. The overall style and language of the documentation must focus on field engineers, not developers. The goal is deployment efficiency.

Administration Documentation

is here: Administration and Configuration Guide. Do not forget to update it if you add or change functionality.

Was this page helpful?

YES NO

Thanks for your feedback