I've been using UML 2.x for several years and it really worked for Object-Oriented languages like C# and Java especially when the software was big enough to be considered an enterprise-level system.

Now I'm working on different systems with different paradigms and considerations, mostly using Python. The team isn't that big, we don't do RUP and stuff, we use a modification of Agile Scrum.

The projects are outsourced to our team so we need to document them properly. However, UML seems too much and sometimes inappropriate, specifically in class diagrams.

As a matter of clarification, we do use docstrings and we export them as part of our documentation. The problem is presenting the big picture.

Any recommendation?


  • Note: neither Java or C# are "pure" object-oriented languages. – Spotted Jun 5 '18 at 8:43
  • 3
    Give an example of what you would like to document, or what kind of software this is. In the current form, it is IMHO quite absurd to ask strangers on the internet, not knowing anything about your software (except it is written in Python) to give you a sensible recommendation. We could only guess around what might be of use to you. – Doc Brown Jun 5 '18 at 8:48
  • I'm trying to illustrate relationships between parts of my system, how they interact and their purposes. @DocBrown One of my problems is that I need something like Class Diagrams but not all my modules contain classes. Instead I only have functions in some modules. That being said, I would need something like a sequence diagram but allowing to use function instances in addition to class instances. – Ashkan Taravati Jun 5 '18 at 9:44
  • @Spotted I edited that – Ashkan Taravati Jun 5 '18 at 9:44
  • Does it need to be a formal software modelling standard, like UML, or can it be informal boxes and arrows schematic pictures that explain how concepts and ideas in your software relate? – Kasper van den Berg Jun 5 '18 at 9:56

Use UML, just the parts you need.

In general you don't have to use full range of UML capabilities. In reality you never really do.

Just use whatever you need. Even if your function isn't packed into a class it effectively serves the purpose of some communication between some entities. So use the sequence diagram.

The benefit of such approach is that you use a well established standard and it'll be easy to explain it to anyone. Also even if you don't follow OOP principles fully it's good to keep them mostly regardless if the language you use enable that or not. It's beneficiary in the long run (easier maintenance). And in every language you can write OOP like style.


Okay. So by further expanding @Ister's answer, according to comments, I concluded to do as follows:

  • Model my modules as static classes as @esoterik suggested.
  • Pick those UML diagrams which seem to be relevant.
  • Expand diagrams with my own conventions to make them more descriptive. as @DocBrown pointed out.
  • If in any case, UML turned out to be inexpressive, I can come up with my own notation. As @esoterik and @KaspervandenBerg explicitly suggested.

Although this seems to be pretty rare to happen as we don't have strict rules about how to utilize UML diagrams, so we are allowed to use them intuitively in order to tailor them according to our needs.

There is no "law" which forbids you to replace the names of objects by the names of modules involved.

The main confusing point was that UML actually uses an Object-Oriented design approach while python doesn't always conform to that, especially when standalone functions are used. But that shouldn't be a matter.

Also even if you don't follow OOP principles fully it's good to keep them mostly regardless if the language you use enable that or not. It's beneficiary in the long run (easier maintenance). And in every language, you can write OOP-like style.

As I googled around about how people use UML with python, I reached the fact that almost nobody designs a software before it is developed in python; at least not with UML! They use UML generators instead when the code is ready, which has its own drawbacks.

Python objects can be extended at runtime, and objects of any type can be assigned to any instance variable. Figuring out what classes an object can contain pointers to (composition) would require a full understanding of the runtime behavior of the program.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.