Documentation is one of the things that developers don’t like to do much – but it’s something very important not only for newcomers to the project, but also to the people who originaly have written that code. We tend to forget what’ve done two weeks ago, so it’s always good idea to write down what we were trying to achieve with that code. Apart from the docs, it’s very useful to have a drawing which will provide a high level overview of the architecture of the app we are doing – what classes, value types and protocols we are using, how are they connected to each other and what methods and properties they have. Something like a UML class diagram of the current state of the project.
Note: We have a new tool now, have a look at it here.
For other languages there are several great tools available, but with Swift being a young language, there is still a room for improvement. There are tools that can create graphs out of the code, like this Objc Dependency Visualiser and this Swift Relationship Graph, but they are not generating class diagrams. One person who is tackling this is my buddy Jovan Jovanovski, with the help of another one of my buddies, Zdravko Nikolovski.
How does it look like?
They are doing an open source library (https://github.com/yoshimkd/swift-auto-diagram), which provides fast and easy generation of an html page with class diagrams of the current state of the project. How to use it? These are the three steps:
1. Clone the git repo:
git clone https://github.com/yoshimkd/swift-auto-diagram
2. Run the generateClassDiagram.rb script with the path of your project as an argument:
ruby generateEntityDiagram.rb ~/workspace/my-swift-project
3. Open the generated html and enjoy the diagrams of your classes, structures and protocols.
After the html is generated, you can drag and re-order the drawn classes in any way you want. All of the different types (classes, structs, protocols, extensions) are in different colors, making it easier to distinguish them.
This script is implemented by string manipulations – all of the types with their properties are extracted from the Swift files and send out to a drawing library which creates the needed html.
If you don’t specify any command line arguments then the script will search for all swift files in the script’s main directory. You can specify any number of command line arguments which should be existing directory or file paths. The directories will be searched in depth for swift files recursively.
Good thing about this being a ruby script is that you can add it as a run script phase to your project’s Build Phases. The script will update the html of the class diagram any time you build the project, therefore always providing an up-to date overview of the state of your project.
This simple tool might be handy to any Swift developer – it provides a visual overview of the current state of your project. It’s also useful for explaining the architecture of the app to newcomers in the team. Still, there’s a room for improvement of this tool and the creators of it would be more than happy to accept your pull requests and bug reports. For example, one thing that needs to be improved is opening the html diagram in Safari – currently it works best on Google Chrome.