As topic says. How you people do documentation of blueprint code. Something more than simple comment node. There is that documentation node that lets you load UDN page, but i could not find anything that can store more than few lines for my project. Already several times we were puzzled about code done 2-3 weeks before, and now our code is getting into areas that are quite puzzling when you do not know trick behind scenes (ie. interfaces mixed with blueprintable components and sending data up and down hierarchy, but standalone “droppable” components are so worth it).
So i kind of need some good documentation inside project. Would be best if i could add clickable local (to project) urls as node comments.
1# Always give properties (variables in C++ land) long meaningful distinctive names; some have what I call ‘C++ coder syndrome’: they name everything cryptic like ‘Ihwmtg’, a, i, ab, char1, bpholder, etc… That is horrible, hurts.
You won’t remember that **** later or what you meant by naming it that way.
For functions and sub graphs, the same applies.
2# Comment groups and blob notations are your friends; pretend you are yourself just a brainless compiler, take notes, lots of notes. Tooltip fields, use them too.
3# Take graph screenshots or pastbin copies and add reference/links to gdd docs with the ‘why’ it is what it is; never leave all project management relying onto editor environment… Your project may not open tomorrow.
yes descriptive naming is thing i always do, that is something i learned in 1990s when i was doing basic and asm.
comments and blobs are not enough anymore, that is why i posted this topic.
I do backups after every major feature added. for eg zipped as: myCoolGame_Flamenwerfer.zip , when i added flamethrower, this plus time sorting lets me pick backup i am looking for in case i removed something that turned to be needed again later.
Ps.
real reason i need real documentation this time is that we (coders in my team) added some “too cool to be usable” code. Yes I always try to stay away from “look how leet programmer I am” code as it is almost always unnecessary complicated and hard to understand. But this time it allows communication to any blueprint class, and it is standalone, no need for coding all those cast to for each class it can be possibly used with. It uses same interface for communicating both ways (to target actor, and from target actor) which is quite confusing now, it will be major ?!?! in few weeks. So i need possibility for adding like 1000 characters comment in few places that is readable.
Another thing that helps is to encapsulate your logic in functions, ideally each function should only do one thing and be clearly named as such. It’s much, much easier to figure out what a blueprint is doing if you organize most of the logic into functions, and make sure you fill out the tooltip field on functions.
Even so, I still struggle with this as well - there are times when I feel the need to be more verbose than the comment nodes really allow for.
Standard tooltip and comment are usually enough for functions. Also instead of functions I am doing specialized blueprintable components that hook to parent and read its data. Those usually need to have maximum 3 functions.
For eg. blueprintable component system that manages lights:
when i add that component to blueprint actor (or just light) it checks for point lights there. Teen hooks to player controller dispatcher for changing lights events. When dispatcher is called it gets color information, and sets light to that color. So basically 3 functions: find light in parent, hook to dispatcher, change light color.
Such small stuff is fine with tooltips and comments only.
But when i try to make above component more versatile, i am using interfaces, and its when all that starts to be counter-intuitive, so i would love to document whole thing now.
Documenting on the code itself is 1 thing but maintaining an external documentation is also a good idea for complex code.
I come from a web and software development background so using agile methodologies a lot which you don’t normally do so much documentation up front but you document during coding to make sure things are actually up to date.
Would be awesome to see something like Sphinx or Swagger that can do automatic documentation for blueprints.
Another thing that we completely miss out on by doing blueprint’s is code testing. Something very easy to implement in C++ but impossible with blueprints.
Source control since everything is in .uasset format also doesn’t help much for debugging blueprint code problems because you have to get the file to be able to inspect it in editor or do manual comparisons rather than just see a diff. Although I could be wrong about that part.
Luckily i am working as reverse engineer, and my 6th sense about where bugs are hidden works in blueprints.
From lack of replies here, i am assuming that there is nothing better than comment box and blob text. Which is sad.
I think i start some wiki page to comment my project. Maybe will dig later into editor extensions and create external document link (or copy udn documentation node and change url).
Ps. I think i know why we do not have external url that can link to arbitrary url. This would be very easy way to exploit unreal and upload malware.
Yeah its not so easy. I use comments and tooltips inside unreal. Another good thing is putting all variables into well named categories. Then I mostly use exsternal sources. I use xml and databases etc to copy all my variables and nexr to each one I write a brief description so that if I ever forget what a variable is for I can easily look it up. And then I use open office and what I like to do is visually map out program functions and events using data flow diagrams etc .
That mapping flow of game is something i did not even try. Instead i am using small specialized components and interfaces. So when that stuff is added to blueprint i can see all its functions by looking at list of added modules. Sometimes i even write such module that is used in single place (for eg. keyboard input for player character) to have all code contained in one object.
External documentation is pretty much required if you want any lengthy description on what your code is doing, and really should be done anyways. Like someone said, your project may not open tomorrow. None of those backups.
Doing a personal blog of the information on a stable website that will be here tomorrow is a good choice. Then make a backup of that information on your system. Store it in a stable cloud account.
A well managed personnel blog (even if its not public, which it probably shouldnt) is invaluable. I find it quite useful and if used right you can categorize everything and make it quite easy to back track to see why you did something or how something hooks into another system etc etc.
I know its external but as you said yourself Commenting your code and using Block Comments can only go so far. Most of the time i will write a large blurb Block Comment at the top of each Blueprint explaining how the systems work and what is intended to use them, just so that if i need a small refresher its there in the code.
Apart from what has already been mentioned, I have found a couple methods that aid the documentation process. Most of this boils down to data organization, and the visual layout of your blueprints will go a long way towards making your blueprint documentation more readable.
Color Coding Comments. My Events(OnBeginPlay, Custom Events, Tick, etc) are all encapsulated with red comments. UI calls are all brown. Print strings are purple/pink. Other things are color coded based on common areas. You look at a giant graph and your brain can immediately parse what is going on. Not looking for UI? Ignore the brown commented areas. Helps get down to the meat pretty quickly.
Centralization. Make a hub where everything of a certain functional area goes through a controller blueprint. If any of my blueprints wants to know about or do anything to the map, it calls the map controller. If anything wants to transition to a new screen, load/unload a widget, etc, it calls to the UI controller.
Centralization has a few benefits.
You keep coming back to the same area of blueprint. This reinforces your memory of how that area is arranged and what it is doing. Makes the documentation you have for a given function more useful.
If the entire project contacts the controller to perform a function, then updating that function does so for the whole project. If you have the same function copied in various blueprints then things can get out of whack when iterating, such as when those functions are slightly different in each location.
By centralizing the interactivity of your project, each blueprint can focus specifically on what it was meant to do. This reduces clutter which increases the speed at which you can grok a function that you haven’t seen in awhile.
*Note that not everything can or should be centralized, but where it makes sense it is a good way to organize your blueprint structure.
Grouping. Once centralized, you can group areas of your blueprint according to what they are dealing with. My UI controller has an area dealing with screens, an area for hud widgets, etc.
Consistency. As much as possible, do things according to a pattern or system. Whether that is naming your files, or writing comments, or whatever. The more organized and streamlined your systems are, the less mental clutter there is getting in the way of understanding what is going on.
For that centralized place for code. I am rewriting whole project for components and interfaces. Even if component is used by single blueprint and does single task (like keyboard WASD input for pawn) it is worth to close all that inside component. Kind of forces me to keep all related code inside it.
For eg. one functionality: one component and one interface. Components are called BAC_whatever (Actor component) BSC_whatever (scene_component) then interface would be called BI_whatever. Each interface has 2 functions: 1 to communicate down to owner, one to communicate from owner to component.
When for eg. I want something done by player character, i drop there BAC_whatever, add BI_whatever interface. Then from component i find owner cast to BI_whatever interface and call function. No matter what owner class is, if it has interface i always can call it.
This lets me literally drag and drop functionality into blueprints. Change lights by events, Fire, stop fire, damage system, all this is (or will be done) with components that i can just drop on actors. This greatly helps organizing code, now all my code is split into components, that each has single functionality. But also requires good documentation about what does what.