Blog / FAQ


UML diagrams and Literate Code Maps from code in GitHub repositories - instantly!

News - November 2023

  • Fixed Objective-C parsing.
  • Added Typescript syntax highlighting to Typescript UML fiddles .
  • Download diagrams as SVG.
  • Permalink URL fixes.

News - October 2023

  • Typescript UML fiddle (beta)
    • Parse Typescript syntax
    • Advanced diagram generation incl. parameters and types on method parameters
    • TODO: Fetching Typescript code from GitHub repositories and saving diagrams generated from Typescript

News - May 2023

  • List your own private and public diagrams first in the Diagrams dashboard.

News - February 2022

  • Python parsing: More robust handling of type annotations on function and method arguments e.g. def foo(a: Optional[str]):.

News - Dec 2021

  • Python parsing: Matrix Multiplication operator @ now parsed correctly.
  • Python parsing: Handle multi-level parameter type annotations, not just param: TypeA e.g. param: TypeA.TypeB etc.

News - May 2021

  • Handle type hint x: Optional[TYPE] syntax.
  • Increased UML fiddle capacity for Pro users, incl. better warning messages. See New Diagram/UML Fiddle
  • PlantUML diagram editor New Diagram/PlantUML... operational again.

News - February 2021

  • Better error message when accessing private repos.
  • Determine correct default branch of GitHub urls entered via New Diagram Wizard / Enter Repository Url.

GitUML no longer assumes master is a repository's default branch, and actually asks GitHub what the branch name is. This is because these days new GitHub repositories are created with the default branch being main due to recent GitHub policy changes on new repositories.

News - October 2020

  • Better reporting of syntax errors in Python - two parse attempts are made, one in Python 3 and Python 2. Results of both attempts are now displayed.
  • Python fstring parsing is smarter.
  • Java syntax errors handled more gracefully.
  • C# and Objective C syntax errors now reported.

News - September 2020

  • Python parsing fix - when parsing function or method arguments with type annotations, handle types with . symbol.
  • Protect against blank attribute names.

News - July 2020

  • Better Python decorator parsing incl. @property decorator, @staticmethod and @abstractmethod detection bug fixes.
  • Python type annotation support e.g. self.util: UtilsEngine = None or def __init__(self, restaurant: Restaurant):.
  • Python UML Fiddles now handle Python 3 syntax properly (bug fix).

News - June 2020

  • New filtering UI - remove classes and attributes from diagrams more easily
  • POST payload support in internal PlantUML server, allowing for even larger diagrams

News - May 2020

News - January 2020

  • Fixed bug parsing *args in lambdas in Python
  • All diagrams now in SVG format - ultra high quality, zoomable, text selectable

News - December 2019

  • C# parsing support (*.cs files)
  • Javascript parsing support (*.js files)
  • Delphi/Free Pascal parsing support (*.pas files)
  • New "refine UML" action on main diagram for easy jumping to refine PlantUML area - has ^E shortcut
  • ^G (scroll to the top of the page)
  • ^ENTER to save and regenerate UML diagram
  • PlantUML syntax highlighting
  • Pure PlantUML editor mode, with lots of examples
  • Literate Code Map support

Quick 2 minute tutorial

Demonstrates reverse engineering some Python code then evolving the diagram into a more effective Literate Code Map by adding a "Code Compartment"







Feedback

Please take the time to fill out a short survey on this site.

Also please...

The GitUML Vision

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:

  • Super easy to create diagrams, just click on checkboxes
  • Share diagrams easily with permalink image urls - embed into your own blogs and documentation
  • Diagrams automatically update when you push code using git, thus remain up to date

More deeply

  • UML can't compete with code detail, so I recommend just using it to illustrate key areas that need to be communicated - don't design in UML, only periodically reverse engineer into UML, using GitUML.
  • Onboard programmers more rapidly with diagrams created by senior developers
  • For a more effective diagramming technology, GitUML supports evolving your diagrams into Literate Code Maps. e.g. Add code compartments to your UML boxes containing code fragments and rich text commentary, add numbered call sequences, red cross references etc.

    • The 5 laws of literate code mapping

    • Boxes represent any scope or namespace - be creative
    • Show structure and behaviour in the same diagram
    • Code compartments in boxes contain code fragments and richly formatted narrative
    • Lines representing function calls between boxes are numbered to tell a story
    • Cross reference numbers can appear anywhere to associate ideas

    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.

Isn't Documentation a "luxury"?

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:

  • Build a code map diagram when you want to solve a serious bug or add a big feature - a code map is not just documentation, it is a powerful problem solving tool
  • Get programmers who are leaving an organisation to build some critical code map diagrams before they leave - why let critical knowledge walk out the door?
  • Give new programmers some code map diagrams and an onboarding program to get them started - a programmer who understands your code base more quickly can start to be effective much earlier, saving the company money.

    • I've added a lot of quotes on the GitUML homepage on the cost of onboarding programmers, and the cost of losing programmers.

Yeah but diagrams go out of date

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.

Special UML features for Python and Javascript developers

There are a few Python and Javascript specific UML features, like the ability to visualise modules as objects on the workspace - with the module functions and module variables treated similarly to class methods and class attributes.  Thus programmers who don't necessarily have many classes can instead visualise their Python or Javascript modules. GitUML supports both Javascript, Python 2 and Python 3 syntax, can handle Java, C# and Delphi/Object Pascal.

Python or Javascript "modules" become "visual boxes with the 'M' stereotype", similar to classes which have the stereotype 'C'. 

Sharing diagrams

  • Each diagram has a special permalink that will never vanish, even if GitUML itself shuts down (relies on the public PlantUML public server).
  • Diagrams are rendered as zoomable SVG, meaning you can zoom in and read everything crisply and clearly.
  • All text in diagrams is selectable and copy-able.
  • Use the full featured HTML editor to add comprehensive, rich HTML documentation under each diagram - write an essay if you want! Click on any diagram in the Diagram Gallery to see the resulting page. Edit a diagram to access and edit the Diagram Description area.

Community UML diagrams

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.

Add an "Open in GitUML" button to your GitHub Readme

Simply paste the following markdown into your Readme, replacing the user and repo names as necessary

[![button](https://www.dropbox.com/s/auynuqlfbrrxyhm/open_in_gituml_flat.png?raw=1)](http://gituml.com/ztree_scratchpad?user=abulka&repo=pynsource&commit=master)

which will display like e.g.

button

Why GitHub?

GitHub is where a lot of programmers store code. Its public API allows integration with GitUML.

The GitUML new diagram wizard

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.

What about Bitbucket and GitLab?

Email me if you need this.

What about local files in my development machine?

You can upload files and visualise them.

What about my private GitHub repo?

You can generate an access token and store it in your GitUML user profile, which allows you to securely access your private repositories.

How do I drag boxes around in the diagram?

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.

So how do I build a diagram without drag and drop?

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.

But I still want Desktop drag and drop!

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.

How does all this work under the hood?

This site is built in Python, Django and Javascript.

The PlantUML connection

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. 

Free plan limitations

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.

The Security of your Source Code

  • Your source code is not stored on our server - it is scanned for class, method and attribute names in order to create the diagrams, then discarded. There is a little bit of caching of source code to speed up repeated analysis - and to reduce hitting the GitHub API too much (and reducing your GitHub API quota count per hour), but the caches are cleared regularly.

  • The private token used to access a private GitHub repository is kept in a field within your account details - in our postgres database, which is accessed via Django with all relevant Django security measures in place. By default, Django prevents most common security mistakes - see security - How secure is Django - Stack Overflow.

  • The diagrams themselves can be downloaded as high quality .svg files.

  • If you have done any "refining of the UML" using PlantUML markup, you can always save that markup into a text file and paste it into any PlantUML server (even run your own) to recreate the diagram.

 

Please send any of your feedback to wware.australia@gmail.com - I will be most interested and will reply.

Andy Bulka CTO

WWare Consulting, Melbourne, Australia