UML diagrams and Literate Code Maps from code in GitHub repositories - instantly!
Demonstrates reverse engineering some Python code then evolving the diagram into a more effective Literate Code Map by adding a "Code Compartment"
Have you ever tried to reverse engineer Java code into UML using various Eclipse plugins? Its a nightmare of setup and complexity, with pretty poor results. And the rising star of the programming world, Python doesn't get much love in the UML world either. GitUML makes creating UML diagrams super easy and accessible.
There are some key ideas in GitUML that make it relevant to today's breed of programmer. Here is a summary:
The idea of building a Code Map is based on what many programmers already do when taking notes in their notebooks and reading code. The process of building a Code Map will give a programmer understanding of any complex software behaviour, which empowers the programmer to add features and gets bugs fixed more quickly.
The process of building a Code Map is a secret weapon to tackle software complexity, spaghetti code, and complex Object Oriented code. Spend days browsing code, guessing and hacking - or respect the problem, do it right, and in an hour or two have a solution by building a code map.
All businesses and developers are pressed for time, fixing bugs and adding features. Documentation is often the last thing on the priority list.
Documenting critical code structure and behaviour in GitUML is more than documentation. The documentation happens to be a nice side effect:
I've added a lot of quotes on the GitUML homepage on the cost of onboarding programmers, and the cost of losing programmers.
A key idea with GitUML is to address one of the problems with "documentation": that diagrams are always out of date. With GitUML, diagrams automatically update when you push code using git.
GitUML synchronises diagrams with git repos and auto keeps them up to date - so that the diagrams don't get out of date - the default is to lock a diagram to code in a specific commit, but you can refresh any time to update to the latest master, or whatever branch you are working on.
Browse through community UML diagrams on GitUML.
To publish your diagram, simply click on the "publish" checkbox when editing your diagram. It will then be visible in the GitUML gallery of public diagrams.
Simply paste the following markdown into your Readme, replacing the user and repo names as necessary
which will display like e.g.
GitHub is where a lot of programmers store code. Its public API allows integration with GitUML.
The ability to visualise popular GitHub repos as diagrams is interesting and fun - the new diagram wizard actively seeks out popular Python and Java repositories on GitHub and lets you select them via a combo box.
The wizard lets you surf through popular and "awesome" curated GitHub repositories and visualise the architectures and patterns in them.
Email me if you need this.
You can upload files and visualise them.
You can generate an access token and store it in your GitUML user profile, which allows you to securely access your private repositories.
There is no drag and drop diagram editing in GitUML - because the vision is that we want diagrams to be created and re-created automatically, based on the actual source code residing in GitHub. We don't want to waste programmers time creating artifacts that go out of date.
Programmers can add additional PlantUML markup which gets blended with the diagram generated from GitHub code, thus adding a lot of flexibility. Even if a diagram changes slightly over time (e.g. new methods are added to a class), the PlantUML markup will still blend in ok, in most cases. Here is an example of some additional PlantUML markup
A -- B
this markup will add an association line between class (or module) A and class B.
Of course, if the class to which your PlantUML markup refers is no longer there in the latest commit, then you will need to revise your custom PlantUML markup - otherwise, it is simply blended into the latest diagram.
GitUML only requires that you select repositories and files using point and click. Include and exclude classes, again using checkboxes. The reasoning here is to no waste time with an interactive diagram editor. Modifications to the diagram come from the source code - plus (optionally) any additional custom PlantUML markup text.
If you are a Python developer and prefer a desktop UML tool for Python, with full interactivity (drag drop, zoom etc) see my open source desktop UML tool for Python, Pynsource - reverse engineer Python into UML class diagrams.
This year's major new release of Pynsource now parses Python 3. Has zoom, layout, ASCII UML and PlantUML rendering support. Pynsource is also, as far as I know, the only UML tool that recognises Python instance attributes (not just class attributes). This means that expressions like self.myattr will result in a proper attribute “myattr” in the resulting UML class. Ready to run binaries are available for Mac, Windows, Ubuntu 18 and 16, Snap - as well as an open source Github repo. Community edition free and open source.
GitUML basically converts
Python or Java Code -> PlantUML markup -> UML diagram
and renders the diagram image via the public PlantUML server.
Arguably UML is best used judiciously to understand smaller chunks of architecture that need documenting and communicating. As you refine your diagram, you can check and uncheck the files till you get the interesting subset you want.
Thanks for all the feedback so far. Re the free plan - I'd be interested in what people think is a reasonable set of limitations and will tweak the settings. Same with the Team plan pricing - I'm expecting 99% of people will just go for the Pro plan which is so cheap ($2/month) that I was hoping to make money off bigger corporates etc. with the Team plan, which would subsidise the majority of devs on the Pro plan. Again I am open to pricing ideas, as this is just getting off the ground and really appreciate feedback at this early stage.
Remember, free users can add as much of their own additional PlantUML markup as they want - that's not limited. As there can be many Python classes per module, I'm hoping people should be able to create reasonable diagrams with free accounts.
FYI you can also upload Python and Java files and visualise them as UML if you select "New Diagram / Upload files". You cannot permanently save those diagrams, as I don't want to get into the business of storing people's source code. The upload feature is more relaxed about the number of classes/files you upload - currently I'm not enforcing any limits, though, as I say, the public plantuml.com rendering server limits the size of diagrams it will render.
Please send any of your feedback to email@example.com - I would be most interested and will reply.