2

I'm documenting the current state of a javascript package which is comprised of several modules predominantly consisting of standalone functions. As the result of using callbacks extensively, the package includes nested calls between standalone functions from multiple packages.

With this in mind, does anyone know what is the best way to represent calls between standalone functions in a sequence diagram?

Christophe
  • 68,716
  • 7
  • 72
  • 138
RAM
  • 2,257
  • 2
  • 19
  • 41
  • What do you call _standalone functions_? Please give some code example. – qwerty_so Jun 14 '21 at 18:39
  • @querty_so by standalone function I mean plain old functions that are neither instance nor class methods, thus are not associated with a class or object. As these functions are not associaed with an object then I'm not sure how to represent their activation or lifelines. – RAM Jun 14 '21 at 19:09
  • Well, you can't. Operations need to belong to a class. You could make an dummy class and add those as «orphan» stereotyped operations. But that's pretty much nonsense. If you got a bunch of them you probably should think about refactoring. Or you document it in plain text. – qwerty_so Jun 14 '21 at 19:14
  • 1
    @qwerty_so it makes no sense to refactor code just to fit an interpretation of how to draw a diagram. – RAM Jun 16 '21 at 08:20
  • Sure. It also makes no sense to document things in a way one can't understand their meaning. – qwerty_so Jun 16 '21 at 08:22
  • @qwerty_so your comment makes zero sense. The point of documenting things is to express their meaning. Anyway. – RAM Jul 28 '21 at 19:44

1 Answers1

3

Are the details of the standalone function worth it?

A common wisdom recommend to avoid the trap of UML as graphical programming language. Things that are easier expressed in code and easy to understand by readers better stay as code. Prefer to use UML to give the big picture, and explain complex relationships that are less obvious to spot in the code.

Automate obvious documentation?

Manually modelling a very precise sequence diagram is time consuming. Moreover, such diagram is quickly outdated with the next version of code.

Therefore, if your interest is to give an overview on how the function relate to each other, you may be interested to provide instead a visual overview using a simpler call graph. The reader can grasp the overall structure easily and look for more details in the code:

enter image description here

The advantage is that this task can be automated, using one of the many call graph generators available on the market (just google for javascript call graph generator to find some). There's by the way an excellent book on further automating documentation, that I can only recommend with enthousiasm: "Living Documentation: Continuous Knowledge Sharing by Design, First Edition"

If you have to set the focus on the detailed chronological sequencing of the calls a call graph would however not be sufficient. In this case, the sequence diagrams may then indeed be more relevant.

UML sequence diagrams with standalone functions?

A sequence diagram shows interactions between lifelines within an enclosing classifier. Usually a lifeline is used to represent an object, i.e. an instance of a class, but its definition is flexible enough to accommodate with any participant in an interaction.

Individual standalone functions can moreover be considered as individual objects that instantiate a more general class of functions (that's the concept behind a functor, like C++ std::function). This is particularly relevant in javascript where functions can be assigned to variables or used as parameters. So you may just use a lifeline that clarifies this. Up to you to decide how you will name the call message (e.g. operator()(a,b,c) or using its real name for readability ? ):

enter image description here

You can also group a bunch of related standalone functions into a pseudo-class that would represent in your model a module, compilation unit or namespace. Although a module is not stricto sensu an object, you may in your modeling deal with it as if it was a class with only one (anonymous) instance (i.e. its state would be the global variables defined in the module scope. The related standalone functions could be seen as operations of this imaginary class). The lifeline would correspond to a module, and function calls would be represented as synchronous messages either to another module or a message to itself with nested activation to visualise the “nested” calls.

Christophe
  • 68,716
  • 7
  • 72
  • 138