All Questions

Community

C
Renato Carvalho

Documentation

Great course!

How do you document a project that complex? How do you keep track of how components interact with each other, including their nodes and scripts?

And what software do you recommend for that (if any at all)?

I feel like I'll have to revisit several lessons to remember how things were done (specially after a few weeks or months from now), so I can tweak some of the code, that's why I'm wondering how to document it.

  • Nathan Lovato replied

    Thanks Renato.

    When it comes to documenting our code, we first try to keep the code itself as easy to browse and read as possible.

    In production, if we were making a game, I'd ask teammates to add docstrings at the top of every class and above every important functions. We made a tool called GDScript Docs Maker to generate a code reference for your own code until this feature becomes part of Godot with Godot 4.

    Now, that doesn't tell you how to use scenes in the project. For that, I would try to write the shortest and simplest guide possible. That's typically what we do when projects grow and, as a team, we only write extra documentation as needed: someone uses something in an unintended or unexpected way, or asks for how some part works.

    My approach is to really try to refactor, trim, and make things as intuitive as possible because the more docs you have, the less people will remember everything.

    As far as keeping track of interactions in the code, ideally we'd want some tool to generate a graph for us from the source code. Keeping track of signals in particular can be difficult. The thing is we don't have that and so there again I prefer to focus on strong guidelines and refactoring to limit complex interactions.

    If you do want a graph for your team, you can use some UML or vector drawing tool. But like all other documentation, one issue is you must maintain it diligently - outdated or incorrect documentation can sometimes cause more trouble than it helps.

    All in all, when a project gets complex, it just gets complex. I'd say the more you can keep your code easy to read and simple, the project structure meaningful, etc. the better.

    Then, the more you can automate the documentation with generation tools, the better. We had an idea for something that'd show a graph of signal connections in your code but haven't gotten to writing it yet.

  • Razoric replied

    The biggest rule of thumb is to reduce your technical debt. Technical debt is "work that needs to be done to keep the project going", and the longer you put it off, the less you want to do it, and the more it amounts, and the harder your project becomes to maintain.

    You can reduce technical debt by ensuring that whenever you get something working "right", you must then make it work "nice". And follow Uncle Bob's advice of "leave the code base a little bit better than when you found it", even if it's not by much.

    That will make managing growing projects easier - otherwise, follow Nathan's advice of naming things clearly and making visual or written aids.

  • Bearskij replied

    I have this problem too.

    Code is easy to document, but the nodes and scenes that creates "hidden" code and interactions are very hard to find any way to document. Especially as there's no corresponding text/json/properties file that you can add docs to for the properties of nodes and systems. Which, in turn, themselves can contain layer after layer of properties and resources.

    For a simple example, how do I document a particle effect? Somewhere there needs to be a description, an intent, conclusions of why the properties are like they are and how the effect should tie into other nodes and/or code.

    I think Unity, Unreal Engine and all other editors that mixes visual coding with text coding have this problem.

    My idea, as I've not done anything important yet in Godot, would be to create a text file next to each .tscn explaining the scene and nodes that need descriptions. Like `MyParticleEffect.md` next to the `MyParticleEffect.tscn` or similar.

    It does require more effort than just having doc blocks right next to code, but I believe this is the cost of the visual coding that gives other benefits.

  • Nathan Lovato replied

    The closest thing you get is the field at the bottom of the inspector where you can type an editor description. I think it gets stored in the scene file so you should be able to extract it and use it in a documentation generator.

    Do you need to document a particle effect or a scene though? Do you think it would have more benefits than it'd cost you time? In my experience, the less documentation, the better, mostly because it's difficult to get people to look at it and keep it up to date. While you can check something lacks documentation with a git hook, you can't know if it's up to date.

    The idea with visual things like a scene is if you name things well, just looking at the scene should give you a lot of information on how it works. Sometimes something may work in an unusual way, but in my experience it's always been tied to a script where we could write our docstrings.

  • Bearskij replied

    I hadn't even noticed the description field, it even comes up in the tooltip when hovering the node!

    As for having to document for example a particle effect.. It's a bit harder to explain. First, I took particle effect as an example because it has so many layers of complexity, properties and resources that in turn have resources. I see the visual coding of a scene as an API for that scene class. You need to access certain nodes in instances at certain points, and a particle effect (and any other root node) can have several nodes building on the effect.

    This is where documentation becomes important as the project grows. You need to know what nodes have to stay a certain way (or have to make a project wide refactoring) and what nodes and properties that can be changes or even is meant to be part of the scenes API.

    You can often make this easier with signals.

    Sometimes you can guess what does what, but it's still a guess and programming by trial and error is kind of frustrating in the long run. When it comes to code it's usually easy, because the class names, function names and type hints tells basically the whole story, in most situations. With functions you keep them simple, if you can, a couple of lines is often enough to follow single responsibility principle and also easy to read.

    Nodes, though, are very different from functions as you can't choose to keep nodes simple, they always inherit and make use of hundreds of properties and there's no way to name a node well enough to know what property it mutates. Every node have a multitude of responsibilities and every subnode gets mutated from its parent, via view and transform matrices, breaking basically every SOLID rule there is. To get back to a project a few days later and start assuming things and spending all weekend searching for non transparent bugs.

    Another reason for some documentation is that it leads to less code duplication. If you're not entirely sure how to reuse what you have already have you tend to create new things from scratch over and over in the project, which eats a lot of time. It feels easier at the time to just make a new particle effect scene, "It will be quick", than going through all properties, resources and subscenes to figure out how it all fits together.

    5 hours later you have your 3 new sprites, a brand new script, global event signals and all properties for it perfectly setup. Weeks later you look at your assets and wonder why the heck you've made those twice, but you don't really remember wasting any time.

    It's definitely possible to do proper coding with Godot, that basically doesn't need any documentation (unless your boss demands it), but you can't have both that and have the nice editor wysiwyg experience.

    All that said, the description field will be perfect for my smallish projects, and I'm also looking forward like crazy to Godot 4 and the improved EVERYTHING. =)

    Good luck with the kickstarter, btw!