Documenting the Design of a Module

Module Design
1

As I have been working on my module, maybe an hour or two one or two days a week with lots of interruptions, I find myself spending almost as much time navigating around the module in the editor just to refresh my memory about what traits I assigned to which pieces (all by prototype) and what each trait enables that group of pieces do, as I spent actually adding to the module by adding parts, adding properties or traits to those parts, or modifying these.

I have taken screen shots of things in the module while I have it up in the editor and printed those screen shots. That has helped some, but it is cumbersome.

Are there any tricks to get a view of the details of the module without having to scroll around opening up the properties windows one at a time in editor (I’m not talking about the code that the editor generates)?

Thanks.

2

I’m afraid the only solution I can think of is to open the buildfile.xml file in a text editor and learn to interpret it. Sorry!

1 Like
3

I typically keep everything in my head during the months of development, that doesn’t seem to be a problem. Revisiting a module a year or more down the line? That can be horrible. Keeping everything neat and tidy and comprehensible is something I think I’m slowly getting better at, but still a long way to go…

1 Like
4

Vassal does not have commenting features built in, so that’s a barrier to start. Oh, one can fake it a little, but still it’s a problem. When I create modules, I do not abbreviate names, so my property names can be pretty long, but it helps a lot to document them.

If the module is complex, I often create an accompanying text file that explains to the older me exactly what I’m doing and how I’m doing it. This can help a lot. Unfortunately, the older me will read the younger me’s note and blurt out: “what are you babbling about, you idiot?” But still, the intention was good and helpful somewhat.

3 Likes
5

I’ve made it a habit to document every key command’s purpose in a separate text file along with a a running log of open and closed tasks. I also use Excel formulas to concatenate Beanshell expressions because the lack of debugging features makes troubleshooting typos in complex expressions far too time consuming.

2 Likes
6

When I work in a module, I have an spreadsheet where I document:

  • All the commands I have defined, including context and any automation
  • All the properties i have created
  • A hierarchy of game piece prototype definitions I have created with a short description of its traits.
  • A project plan (kind of) whit all the tasks I want to do.

This usually is enough for me.

I have think more than one in writing a small XML parser for extracting the relevant information (for me) from the buildfile. But never did it.

1 Like