When meeting some friends or family that you haven’t seen for quite a long time, people generally ask you what you are doing for a living now – or where you are in terms of studies – this is generally something you ask or you get asked for.
If you are a student in computer science, or computer engineering, you mainly explain that you are working with computers, solving hard problems, and that you are building software to do it.
Generally, people are curious about the type of software you are building and ask questions like the type of software you build. And you generally answer that you are building websites, mobile apps, programs that make planes flight, things to do some kind of simulations, ‘stuff’ that perform some kind of optimisation, etc.
But sometimes, you get a rarer question: why do you build software?
And you generally you pause and wonder, and then maybe simply respond something like ‘because it’s fun’, ‘because this is intellectually stimulating’, ‘because I like it’, ‘because it is useful’, or ‘because I can make a living out of it’.
But if you think of it, this answer can be used for any type of jobs or social activity.
So, what is special about building software?
This can be a binding question, and the answer may depend on what you are looking for.
On one hand, it can give you a way to easily create things that do something relatively efficiently and cheaply. Unlike building cars or whatever physical things or objects, you can put a relatively small initial investment in software and get a relatively large output out of it – be this investment quantifiable in terms of money or time. Hence, building software gives you a concrete ability to translate ideas to something you make profit from.
On another hand, it might be seen as rather special way of interacting with the world, of producing something. This is a sort of art, and science: a sort of craftmanship. Unlike building cars or whatever physical objects, by just writing it gives you a special form of freedom and an ability to easily translate ideas to something you can build, share, modify and build upon.
Hence this more precise question: Do we build software to make something work and gain something else out of it, or do we build software to reach this form of real piece of human craftmanship?
The first one is necessary but isn’t sufficient: the second one might be the nicest and most meaningful goal of every software project.
How to reach a real piece of craftmanship?
There is no secret: this comes with skills, hard work, and hours you put into it: one could have fantastic ideas, inspiration and motivation, this won’t get you produce something.
You can build software alone, but you generally create it as a team. And, in a team, everything is a matter of building a common knowledge, a distributed ownership on the software.
This comes with mutual trust, organisation and communication. One day I came across this – apparently famous – text from Melvin E. Conway, How do committees invent?. This text is quite long, and quite old – some kind of the typical article that is rediscovered every two years or so. The main take away of his point is this concept of homomorphism between organisation and systems that they produce: in short, ‘Any organisation that designs a system (defined more broadly here than just information systems) will inevitably produce a design whose structure is a copy of the organisation’s communication structure’. This view can be applied to organisation building software, but not solely: if you have four teams working on a software, on the long-term, you’ll get a software that can be decomposed into four parts. If you have people that are organised, you are prone to get a software that is organised as well; if you have people that are communicative, you are prone to have a software that is easily understandable; etc.
Be this text quite abstract and logical in its willingness to prove its point 1, their main arguments are valid.
How to ensure that a proper communication can exist within an organisation to better build a software?
Tools to communicate and document efficiently
In my first internship, we once were visited by a senior software engineer coming from a bank. The goal of this visit was to present the technical stack and the way they built the way their own ETL, storage and processing pipelines of data was built, in order to share knowledge, good practices and risks.
The presentation was clear, concise but exhaustive. People were interacting with questions about a lot of different ways things were done, design decisions were made, technical details were handled. The full session last for nearly 45 minutes. Do you wonder what was used to conduct such a presentation? A small deck of slides, consisting of the minimalistic number one slide. Yes, one slide with a UML diagram.
Back at university, one professor was spending literally lecture explaining the pros of UML. I was quite convinced but a bit sceptical about the acceptability of such a framework in companies. But after this presentation, I understood the real power of such a language.
In the world of agile and scrumbatic workflow, it seems that people do not really know or believe or dare considering UML those days 2. But something like UML is a tool we need to better communicate, to better create a shared knowledge, to aspire to building better software.
The Problem of Documenting Code
I sometimes came across code bases that were relatively hard to understand; in those moments I would really have liked to have an overview of it first, rather than to jump into the details. Moreover, I am myself working on personal/hobby projects and I would like to help myself a bit with documenting those projects and keep them up to date as the times goes on.
I have been using a presentation language for UML, PlantUML 3, after a really quick and serendipitous suggestion of someone in my first company that wanted to document they work. So far, I’ve used it to document projects or even sometimes to just expose gut-feeling design propositions to people – to myself when I need to organise my thoughts.
Using Atom and some extensions 4, you can be easily draw something in minutes: the syntax is really easy to learn and use, and what you start generally ends up being the actual pieces of documentation you wanted to have 5.
Yet, the main problem of documenting software is not to write it, it is rather to maintain it in phase with the code: updating an old documentation is really a pain in the neck, because you have to keep track of what is still existing and what is not if done manually.
Tools exist to have the documentation being in phase with the actual code: this is for example of the case of Sphinx or Doxygen. Those tools are useful, but stay at a lower level of code documentation: the signature level.
I am convinced people do have this issue of trying to understand the code base rapidly while minimising their time and effort put in actually documenting this bigger overview. And I am certain that people would be prone to learn UML if they can use it in a really efficient way.
A Pragmatic Proposition to Document Software
A quick reflective example
Let’s give a quick example of it, with using its source code directly.
The whole source code is contained in a
./pulm/pulm.py. With simply cloning
the repository, you can generate the PlantUML script with:
$ ./pulm/pulm.py – path ./pulm/pulm.py
What you’ll get is a textual description of a class diagram of concepts used in
You can embed it with
plantuml to directly generate raster or vectorial
pictures of such diagram with:
$ ./pulm/pulm.py – path ./pulm/pulm.py | plantuml – p > out/pulm.png && open out/pulm.png
and you will get:
Now, let’s say you want to have an overview of your code as this is being modified, you can simply use a simple script like:
1 2 3 4 5 6 7 8 9 10 11
#! /usr/bin/env /bin/bash ## Automatic compilation on change INFILE=./pulm/pulm.py OUTFILE=out/pulm.png open $OUTFILE while sleep 1; do find . – name $INFILE | entr \ $INFILE – path $INFILE | plantuml – p > $OUTFILE; done
Disclaimer: this has not been tested to intensively; this is maybe not really efficient too ; but it works in some case.
This is really minimal for now: I am currently re-documenting previous projects with it, fixing things so that it works more generally usable. What I see for this tool is a usage similar to other tools like Flake8 that can easily be integrated via continuous integration and whose artefacts can be integrated in an online documentation.
This needs some more thoughts and design: contributions are really welcomed!
- See the ‘proof’ and diagrams, in the section Relating the Two. ↩
- With the main reason being that the time you spend documenting code of your software, is time you don’t spend writing it. ↩
- People also use Mermaid that is pretty nice to draw diagrams but this tool is maybe more suited for diagrams PlantUML does not handle such as Gantt diagrams or git branching diagrams. If you would like a good overview and comparison of those two tools, this blog post comes in handy. ↩
- Though you might need some arrow layout with more than 10 classes, it is quite manageable to get to something readable and ordered. ↩
- This is a short for ‘Python ULM’; ULM for ‘ultra-léger motorisé’, a really lightweight plane in French: something simple that gives you a broad overview of the landscape. Also a small pun for UML. Yes, as you’ve guessed, I was not inspired at all to find a good name. ↩
- Some projects are or were existing but their status is not clear: PyCharm does have a UML generator, but this is available only the Enterprise Edition of the IDE; there is also Pyreverse but the state of this tool and the way one can contribute to it is rather hard to find. ↩