UML diagrams are only helpful for people who understand software architecture, which is not even most professional developers in the last decade and a half, let alone most Godot game developers.
2 Likes
They are easy to read. A class diagram or component diagram often suffice. @dragonforge-dev
They are easy for me to read. But Iâve been training developers for over 2 decades now, and I can tell you that most have never seen one and donât know how to read one. Because they donât need to anymore. Software development has changed a lot in the last 50 years. Software developers no longer need to architect software to have a full time job programming. Just like car mechanics do not need to know how to design a car to work on one and be gainfully employed.
They are typically overkill outside of the design phase. They are hard to maintain, unless you are programmatically generating one. They were very useful for waterfall development, but since Agile started taking over in the early 2000âs, they donât really have a place anymore. Personally, I have my wall covered in them right now, and I whiteboard things like that out - but I donât use it for documentation anymore because no one looks at it.
2 Likes
Your experience is definitely different from mine. The keyword is âstableâ. They are not attached to waterfall, by the way. They are just an extra tool. Thereâs nothing too scary about them. I havenât met any developer who cannot understand a class diagram.
1 Like
I never said they were attached. UML was developed in the mid-90s, and developed from there as it was adopted by more companies, and became an ISO standard in 2005. But UML diagrams faded out as Agile software development practices became more mainstream.
UML diagrams are overkill IMO for solo devs, and even small teams. User Stories and a ticketing system are much more efficient. Once something is stable, sure it canât hurt to develop a diagram.
I have no idea what your experience is, but Iâve been developing professionally since '94. Iâve seen things change a lot in software development.
I didnât say they were scary. But I think youâre assuming a lot. Try explaining a class diagram to someone who does not understand OOP. Try explaining a class diagram to someone who thinks itâs a waste of their time when they have projects due. Try explaining a UML diagram to someone who does not care about the architecture, does not know how databases work, or does not know how HTML works, and does not care to learn. Try explaining a class diagram to a functional programmer who does not use classes.
Yes, developers who like and understand OOP, and have experience programming in an OOP paradigm can easily read a class diagram.
But again, we are in a Godot forum, talking about what kind of documentation should be done for Godot projects. Most people coming here for answers do not have OOP knowledge or experience. So your class diagram is going to go unread. Because either people do not have the knowledge to do so or theyâre bitter experienced developers that do not trust documentation (see above).
I mean, you do you, but I do not think personally itâs a good answer to the OPâs question.
1 Like
I dont document anything but have started putting more effort into variable and function naming. Something i would have named aim_vector before i will maybe name tackle_aim_vector or fire_aim_vector today. It will often happen that youâll wonder what some variable is for if you have many with similar uses but dont name them clearly enough. It will also help you not reuse the same variable in ways that can cause issues later on. It becomes more clear that âwalking_speedâ is meant for walking and not some generic base_speed for other speeds to be synced with, like tackle_speed = speed * 1.5 (unless you want that).
Even very long variable names are easy to work with. Just ctrl+d the current one until all are marked, then change them all at once. Careful not to include drunk_walking_speed etc when ctrl+d walking_speed.
1 Like
UML has its uses but it generally encourages toxic aspects of OOP (like future proofing and over-systemizingâŚ) to infest your thinking, especially if youâve been taught that OOP is The Way to design and implement systems.
1 Like
I canât write code without commenting. I have faced once the situation where you have to hook back on code you wrote months ago. Let me tell you that now my code is half instructions, half comments.
You should mail that to my teachers who have been swearing for years that OOP is THE way. Theyâve never heard of ECS or any other paradigms, and weâve been eating UML and all those diagrams for years. For them we should have a fully functional system in UML prior to writing code, which imo kills creativity and prototyping.
For several years, as a solo analyst/programmer, I used OOP through Rapid Application Development (RADâŚ) to great effect. It enabled reiterative âmodularâ development, getting a core working (and in productionâŚ) with âhooksâ to add future functionality, and re-model the core if production showed a way of doing so with benefit. No all-encompassing diagrams nor white-boards, just systematic following the project closely on a daily basis. This methodology worked across three different multi-national companies, in different industries, for Production Management. Just sayinâ. 
1 Like
That will change in time.
It is the way. (âThis is the way.â) It is the standard for most professional programming. If youâre learning programming, you should learn how OOP works.
No one outside the game industry has ever heard of Entity Component System (ECS). This is not surprising. Many people have not heard of Functional programming either. People use functional without knowing theyâre using it, for example when creating a recursive function to search a directory (or a Node tree in Godot).
People whoâve never worked in web development, have never heard of Model-View-Controller (MVC). some people who have worked in web development have never heard of it either - which seems insane once you understand it.
It really depends on the experience of your teachers, and if theyâre academics, itâs unlikely theyâve been exposed to more esoteric paradigms.
TBH, thatâs not a bad thing.
Itâs important to learn how to do things the proper way, so that you then know what rules to break. Theyâre teaching you a way to think. Theyâre also teaching you how to communicate in a professional technical setting.
Not at all. UML allows you to diagram out whatâs in your brain and facilitates discussion. I use it all the time professionally to facilitate discussion when architecting something new. It has been instrumental numerous times in explaining concepts to people who could not visualize what was so clear to me in my own head.
However, I also feel that if youâre writing a UML diagram on anything other than a whiteboard for discussion, or a notecard taped to a wall, youâre wasting time. Especially once youâve coded it.
Sure, but I but there was some sort of project management in place to communicate what had to be made next. A Scrum board or Kanban board perhaps? And/or user stories? Or something similar?
1 Like
Nothing formal, really; daily meetings with the services concerned (stake-holders..?) and The Boss kept things pretty open-ended. My being a team of one (for two of the ProjectsâŚ) helped a lot, and having a fairly generous time-line (âfive yearsâ, echoes of a Bowie song..!) was advantageous, too. I donât recommend âseat of the pantsâ as a method, but would encourage RAD thinking as an option, at least. Get something practical working, giving results, and build upon it, re-iterating to keep (or change..?) the final goal in sight and progressing. I donât plan it all beforehand, as, by the time itâs even started, the goals have changed. It can work; other systems are available.
2 Likes
Yeah I forgot to ask what the team size was. Being a team of one makes that much easier.
1 Like
If you feel to comment then you are likely put too much code into a function. Often extracting the code and naming the function and parameters like the comment you were about to write is the way to go.
The one thing i would document as a solo dev is signals. Function calls and setting values are easy to follow. But sometimes when debugging old code and finding a signal, it is like a dead end. Which functions does this signal connect to? What do they do? In my experience, time spent documenting would have been better spent making function and variable names more legible. Signals is the only exception i have encountered.
Hard disagree.
- Press Ctrl + Shift + F.
- Type your signal name into the search box.
- Every use of the signal in your code will show up in a hyperlinked list.
Signals rarely need comments. Documentation makes sense if its a plugin.
3 Likes
Thanks for the tip
1 Like
Not quite, itâll show you anything that has the same name as your signal and you have to sift through all the things that you donât wanted to see there.
I canât wait for a proper refactoring tool in Godot, but thatâs a topic for another discussion
3 Likes
That just gives you a chance to pick better names for things. Also, you can use tricks like adding a space, or using full word match.
Samesies.
2 Likes
What it all boils down to in the end: pick better names! 
6 Likes