One can argue that Software Engineer job is to write a code. Well yes, this is a part of the job, yet the other part of software engineering is reading a code, not writing it. Now if you go deeper into the thought - it is actually about understanding the code, the structure of the projects, it's details, nuances etc.
Nowadays you rarely come to job to start everything from scratch - you usually come to a new job and you see a dozens of folders, hundreds if not thousands of files. Sounds familiar right? And you don't have a clue usually what is this codebase about, so you need knowledge transfer sessions, looking into the code and trying to make sense of it, trying to understand how to run it etc., etc.
Let's take an example - let's go to docker-compose repo page in Github and try to make sense of it. The first thing you gonna see there is:
Looks impressive isn't it? Just another list of folder names and files which gives us only one idea - the project does consist of folders and files. Awesome thing, at list I know now that it doesn't consist of dragons and wizards, that is something which helps me as an engineer to start with. Ah, just kidding - this is terrible and doesn't give you any information about the project. Like if you want to know about tech stack you have either to ask someone or go inside folders to see what's there and try to guess or basically reverse-engineer things.
So after spending some time looking at the code I drew the next picture which I want to share with you:
I agree that this is not ideal, but at least it can give you an idea, that you can visualize project in better way, telling a richer story about it as just a list of folders can do. At least it can show you tech stack right away and it is something can be done automatically by analyzing the code. Github is already doing it but presents an information in very limited way like just a list of languages used in the project.
This is just a simple idea, but think about possibilities. You can show areas for more often used folders bigger, show warning signs, comments, notes right here on the project map. While working on the project you could look at how this visualization is generated and keep your structure accordingly so auto-generated visualization is actually making sense and tells complete story about your project so you can even save your precious time on doing documentation. Following Python Zen lead you can do your code self-documented and make sure that your documentation looks awesome, not just generated as another bunch of files. I'm not even mentioning what possibilities can be open with using of an AI.
So tell me what do you think about it? Do you share an idea what the world would be better if we had such visualizations of the codebase?
Top comments (0)