Examples of documentation models for scripts

Hello,

Do you have examples of documentation models to explain the different scripts that make up the project in order to find your way around?

 

Hello,

When we have hundreds of scripts and we work in groups it is difficult to know what each script does.

How do you document?

 

Hi,

First, use SOLID principles and organize groups of scripts into assembly definitions to enforce decoupling of modules that perform different functions.

Then use standard C# XML tags in your comments. Your code editor will probably set up templates if you move your cursor to the beginning of some code such as a method and type "///". These XML tags serve two purposes:

1. Your code editor will usually show them as a tooltip when it's presenting autocomplete information as you type code, and
2. You can run a tool such as Doxygen on your code to generate an API reference in HTML. You can then put this HTML on your team's website for all of your teammates to reference.

 

The organization of the scripts into a decent structure will save a lot on documentation as many things simply not need to be known to the user of those scripts.
Hundreds of scripts aint very much to keep structured and it sounds to me that if anyone needs to know what every script does then youre scripts have a lot of side effects that need to be known about. SOLID aplies but also critical thinking about how to name things. If you cannot describe what something does in its class/filename then probably its doing too much.

 

thanks, this helped answer some questions i've had recently.

 

I loudly echo the idea that good organisation drastically cuts down on documentation needs, and other overheads too.

As for the comments themselves, focus on what we can't read from the code. What is its purpose? Why is it implemented this way? Any gotchas (easy mistakes to make) when using or changing it? External factors influencing its design?

 

1. A single folder for scripts is fine for prototypes and small games but I think the larger a project is the more reason to divide scripts by feature type in folder organization. Its easier to find the feature then dive into its scripts than have them all jumbled into one place scrolling through all the names. This also brings a slew of other improvements such as ease of upgrading or switching out features.

2. Get better at naming classes. I honestly get a dopamine rush coming up with a good descriptive name of what something is. Its a skill in and of itself. So improve on defining what something is and what something does. if working in a team make sure all team member agree on naming conventions as well.

3. The better you name things, the more powerful search becomes. Start using search at this point with hundreds of scripts. This will pair well with naming conventions.

 

Yeah, there is a concept in software development called "self-documenting code" or "self-describing code", Choose names that describe what your code does and what it's meant to be used for. Come-up with a good naming convention and stick to it.