Documenting your code should be done this way
A tip you could use to document your code efficiently
Preface
Let’s start! I’m sure you’re here probably because at some point you have run into this problem of how you should be documenting a piece of code that you wrote. If you’re just documenting APIs the API docs like swagger would help but it doesn’t help in documenting the logic.
It’s not just you who is guilty of spending a wholesome amount of time just figuring out the application that you’d be using. Yup! I too did feel like Google docs just didn’t cut it out for me. But soon did I realize that even having the fanciest editors or application wasn’t of much help either.
The Realization
The problem wasn’t with what I was using but more related to how I should be doing it. And the solution that I’m going to propose is simple and something that probably you do already know. Yes I’m asking you to have flowcharts and sequence diagrams to document your code. I’m sure some of you might have already lost the interest in reading any further but hear me out you won’t be drawing any diagrams.
But before I jump into the implementation details, I want to jump into the why’s of using the diagrams like flowchart. You might find it primitive and no offense but weren’t you looking for a simple solution in the first place. Instead of writing huge paragraph(s) of text you could have a simple diagram representing it with a short paragraph describing things that you couldn’t include in it.
Notice how I just summarized the entire three paragraphs in a single diagram.
Also with a flowchart it’s pretty easy to figure out loopholes in your code. I noticed it firsthand and I just couldn’t stop admiring the beauty of what this little trick can do to help you code better. And the entire team (Even the ones who don’t code) can chip in to figure out if there’s anything wrong with your logic since they wouldn’t even need to learn a programming language to figure out what’s wrong there. Sweet isn’t it! :)
Roadblocks
Okay! So let me list down what might be stopping you from using diagrams like flowcharts and we’ll address them. Shall we?
- It’s time consuming. For people like me who has an over average level of OCD it’s a nightmare since if I were drawing flowcharts I’d be spending hours trying to make it look perfect. All the lines and stuff.
- It’s not scalable. What if we were to make amends? We’d have to find the editable diagram, open it in an editor, edit it and replace the one that exists. Heck it’s tiring.
- I just want to code. I don’t want to spend time using apps like Gliffy or Photoshop. I like designing but the thought of switching to another GUI app just to document the code doesn’t sound so appealing.
What if I tell you all of these problems can be resolved? Would you believe me? You’d probably have to because I’m going to explain how.
Mermaid
Introducing Mermaid, a Javascript based diagramming and charting tool. It generates diagrams flowcharts and more, using markdown-inspired text for ease and speed. With Mermaid we are going to be writing code to draw our diagrams. Mermaid has a variety of diagrams that you can choose from including flowchart, sequence diagram, entity relationship diagram, gantt chart, user journey and more.
Getting started with mermaid
Even though it’s based on javascript, we aren’t going to be writing code in javascript. Mermaid.js just creates diagram from code you write with it’s own syntax in markdown files. So you could include mermaid diagrams in your README.md files as well.
Mermaid has a pretty straightforward and interpretable syntax. Let’s take an example of a flowchart.
```mermaid
graph TD
id1[Do something] --> id2[Do something else]
```When the above block is added to the markdown and rendered using mermaid library the following flowchart is rendered.
Easy isn’t it. What you did was just provide an id with the text in braces and an arrow to represent the data flow. Now to create another item in the link you just use the existing id and an arrow to point to the new block.
```mermaid
graph TD
id1[Do something] --> id2[Do something else]
id2 --> id3[Do even more things]
```It’s like simple programming with assignment at first initialization and reuse using the same ids. Also the shapes of the blocks are based on the kind of bracket you use so it’s pretty easy to wrap your head around it.
I won’t be doing a full tutorial on how to use mermaid.js here as there are plenty of resources in the internet for you to get started with it and even their own documentation is more than enough. The link to the documentation is here.
If you didn’t figure it out the flowchart you saw near the top of the page was also written with mermaid syntax and its code is as follows.
```mermaidgraph LRStart([Start]) --> CONDITION1{Documentation problem?}CONDITION1 --yes--> CONDITION2{Is swagger what you need?}CONDITION2 --no--> CONDITION3{Does any documentation apps help?}CONDITION3 --no--> CONDITION4{Did you try flowcharts?}CONDITION2 --yes--> CONDITION4CONDITION1 --no--> CONDITION4CONDITION4 --no--> MERMAID[Start using flowcharts with Mermaid]CONDITION4 --yes--> MERMAID```
Can I just start now?
Okay I might have gotten you hyped up for documenting using mermaid. If you use gitlab you’re good to go since it has native support for it. But if you use anything else then there’s a problem. Neither github nor bitbucket supports mermaid syntax in markdown by default. Most markdown editors don’t have support for it. Stackedit is one online markdown tool which has support for it. But I’m pretty sure you won’t be saving your docs in some online markdown tool.
So what do I do?
If you have your documentation stored in github wikis and Readme files, you could just install the mermaid charts extension and convert the mermaid code in markdown files to corresponding diagrams just by clicking the extension icon.
After trying out all the other extensions present in the chrome webstore that are there to do the same thing but finding no luck in finding one which uses the latest version of mermaid and renders all diagrams, I decided to create the extension by myself. It supports github but not bitbucket right now since the algorithm I wrote for the extension isn’t able to recognize mermaid code in Bitbucket sites.
If you use confluence for documentation there’s a Mermaid plugin for confluence. I havent tried it yet but I guess it should work. There a plugin for JIRA as well. The list of all the plugins are here.
If you use Visual Studio code like I do, I would suggest you use Markdown Mermaid Preview Support Extension to see the output in realtime while you write in markdown.
Problem check
I had listed down some problems we might have had with implementing the diagrammatic documentation.
- Time Consuming: Since with mermaid you won’t actually have to be drawing stuff you’d be saving a lot of time. Write a node in the flowchart or sequenceDiagram, it’s automatically created for you. You’ll lose control on how you’d want it to look but guess what it will look uniform no matter who coded it.
- Scalability: There would have been a problem of scalability if you were using gui tools like gliffy to create the diagrams. But since we’re coding and uploading the source code itself, that issue doesn’t occur. And also you’d even get to see the diff of what exactly was changed when you update the diagram in github wikis.
- No GUI Tools: You’d get to do what you love most i.e. code even when you’re documenting something. Trust me it’s as good as it sounds.
Conclusion
It will probably be dumb of me to assert that documenting the code with diagrams only would solve all your documentation problems. But what I wanted to suggest with this article is how you could document your code with the help of diagrams without making a tradeoff on efficiency. You would still need some guidelines to follow in order to make your documentation process standardized and having some diagrams instead of just boring text would make it fancy as well as easily interpretable.
That’s all folks. Hoping this would be of help. Let me know in the comments what you think. ✌🏻😇👏
