6

Goal:

I am trying to create a UML class diagram for a java spring application. Spring uses a lot of annotations and I couldn't find any resources online on how to properly model them in UML.

I know that there is this question and it gives a good answer on how to model class annotations but it does not talk about method or variable annotations.

Examples:

Example class with annotations:

@RestController
@RequestMapping("/someRoute")
public class BaseController {

  @Autowired
  protected BaseService service;
  
  @GetMapping(BaseEntity.ID_MAPPING)
  public ResponseEntity<BaseEntity> findById(
          @PathVariable(value = BaseEntity.ID) long id
          ) throws ResourceNotFoundException {
      
      BaseEntity entity = service.findById(id);
      return ResponseEntity.ok().body(entity);
      
  }

}

For the class annotations I would use this:

class annotation example

For method and attribute annotations I tried using this:

enter image description here

But as you can see this gets very long and complicated to read very fast. This also would not work if something had multiple tagged annotations.

Question:

So I would like to know if there is a correct or better way to show annotations in an UML class diagram? Or if java annotations should even be in an UML diagram at all?

Tim Engbrocks
  • 71
  • 4
  • 1
    UML has annotations which look like post-its. I would usually not over-use stereotypes but that depends (if you run code generation you need it). Multiple stereotypes are separated by comma inside a single set of `«»`. –  Jan 03 '21 at 21:40
  • 2
    Consider what information the readers of your documentation actually need - they want a quick overview of what the class is about and how it relates to other classes. For example, if I were reading the docs, I wouldn't care about most method annotations pretty much at all, I would be much more interested in the names of the methods and parameters. Some of the class annotations could be interesting, not because of Spring, but because they tell me something about the role of the class in the system; e.g., I wouldn't care if it said <> instead of <>, etc. – Filip Milovanović Jan 03 '21 at 23:28
  • 1
    In other words, the idea is not to write the code twice (once in a programming language, and once in the unified modeling language), the idea is to make a judgement call about what's the most relevant information, and present that, ignoring the other details. – Filip Milovanović Jan 03 '21 at 23:32
  • Thanks for the idea with the <> :) – Tim Engbrocks Jan 04 '21 at 08:43

1 Answers1

4

It all depend on the purpose of your model:

  • If it is a design model that aims to communicate the big picture, it would be advisable not to show any annotations: these would on’y make the big picture more difficult to grasp by adding unnecessary implementation details.
  • if it is an implementation model that aims to be ultra-accurate, for example because it’s used to automatically generate code, the you need to find a way to convey all the required details. The stereotypes approach at class level is perfectly suitable. At operations level. the a list of operation properties between curly brackets (e.g. {op1, op2,...} seems the right way. But UML is really not meant to be a programming language, and if there is no code generation, in a matter of months your UML will be out of sync.
Christophe
  • 74,672
  • 10
  • 115
  • 187
  • 4
    There are also some uses for UML between these. Martin Fowler wrote about four [UML Modes](https://martinfowler.com/bliki/UmlMode.html) - [Sketch](https://martinfowler.com/bliki/UmlAsSketch.html), [Notes](https://martinfowler.com/bliki/UmlAsNotes.html), [Blueprint](https://martinfowler.com/bliki/UmlAsBlueprint.html), and [Programming Language](https://martinfowler.com/bliki/UmlAsProgrammingLanguage.html). First, figure out who the audience is and then what the best mode is to convey the information that they desire is. – Thomas Owens Jan 04 '21 at 00:38
  • 1
    Thank you for your answers. I think I'm going to use my diagram to show the "big picture" :) – Tim Engbrocks Jan 04 '21 at 08:45
  • 1
    @ThomasOwens Thanks for the links. Indeed, there are many ways to use UML. One could also mention documentation as code as well as roundtrip engineering. I mentioned only two very common uses, just to highlight the need to think about the purpose of the diagram when it comes to what should or shouldn’t be shown in the diagram. – Christophe Jan 04 '21 at 09:33