This are some comments in response to Dilvish and his starname patch v3 which I said I'm going to post here because they are more concerned with the universe generation script in general than with star system naming in particular.
Ok, Dilvish, here are my thoughts/comments that came up when I took a look at v3 of your patch (and also when I read some of Mats comments on my Python code). These have been in the back of my mind already, but I put them off because I first wanted to complete scripted universe generation at least to the point where all major parts have been ported to Python, and the original behaviour could be reproduced with only limited use of legacy universe generation code.
But as a first major patch to the universe generation script is already about to go in, I think I better bring these thoughts and comments up now. It concerns structure and coding style of the script.
What I'm aiming for is that even people (content scripters) who do not have very much experience with programming have a decent chance of understanding and being able to tinker with the universe generation script. Of course I'm aware that at least some basic experience with programming and knowledge/familiarity with Python is going to be required, it won't be possible to simplify things to the point where one could customize it without that. But I'd want to try to get as close as possible.
To achieve that, I think there are several things we need to take care of when it comes to the structure and code style used in the universe generation script:
1.)
Code readability: We need to strive for simple and readable code and be willing to sacrifice efficiency, coding elegance and performance for that (wherever possible of course). I've already had second thoughts about my Python code and wondered how I could make it cleaner, simpler, more readable, because I've been worried that someone with only basic experience with programming might not get past "Huh?" when looking at my code. A suspicion that Mat has confirmed (thanks, Mat, btw, I know that probably wasn't your intention, but it gave me some very valuable feedback
).
Now, I think I already have a rather simplistic code style, as my own Python skill are rather basic, and I don't know about most of the more sophisticated/fancy features of the Python language. Contrary to you, you're obviously much more adept at Python (and programming) than I am, and I think your coding style reflects that. IMO your code is more compact, efficient and makes more elegant use of the various features a programming language offers. But it also makes it harder for someone not so experienced to understand what's going on. To illustrate what I mean I'll give an example taken from you starname patch:
Code: Select all
stargroup_words[:] = getNameList("STAR_GROUP_WORDS")
stargroup_chars[:] = getNameList("STAR_GROUP_CHARS")
stargroup_modifiers[:] = [stargroup_words, stargroup_chars][ star_groups_use_chars ]
Maybe I'm wrong, but if a understand that piece of code correctly, the following should be equivalent, at least for the purposes of your patch:
Code: Select all
stargroup_words[:] = getNameList("STAR_GROUP_WORDS")
stargroup_chars[:] = getNameList("STAR_GROUP_CHARS")
if star_groups_use_chars:
stargroup_modifiers[:] = stargroup_chars
else:
stargroup_modifiers[:] = stargroup_words
While your version is certainly more compact (I mean, one line with a simple assignment instead of a four line if...else construct), I think my alternative is definitely more
readable, especially for someone with only limited experience with programming/Python. Such a person will probably look at that line and wonder what you're doing here and why.
2.)
Encapsulation: Of course there are things the universe generation scripts needs to do that simply can't be done simple and readable. Some, because the performace hit would be too bad, others won't be doable that way at all. These parts should be encapsulated in a set of functions (maybe classes) with an interface as clean and simple as possible, that (universe generation) content scripters can understand and use without too much difficulty.
IMO that of course requires that the whole process of universe generation should be split up into distinct steps with as less intertwining as possible. Again, taking your starname patch as example: I've seen you adjusted some of the star system generation code, because you already need to determine the star type of a system before it gets actually created for your name generation code to work. And you don't create a system before determining its name because the system generation API function call already expects a name. OTOH, now these two steps (star system generation and name assignment) are intertwined, making the whole code section more complicated and less understandable for the unexperienced programmer.
In this particular case my suggestion would be to "disentangle" these two steps. First, create all the star systems and it's contents (planets) as it has already been done before with temporary placeholder names (e.g. "System " + system id). Then, in a completely seperate step, the content scripter can invoke the whole naming process just by calling a function we provide for him, which encapsulates the entire complexity of that mechanism.
All that leads to my third point:
3.)
Modularization: I've started off with just one Python file containing the entire script, but even at the very beginning I've been aware that most likely I won't be able to keep it that way. Even if universe generation isn't going to be anywhere near as extensive and complex as the AI scripts, I think we should split it up into several modules which get imported and employed by the main script (like it's done with the AI scripts). It has been already quite big even without your patch, but now I think we've reached the point where we really should do that. I suggest you commit your patch, then I'll make the necessary preparatory changes, that is, create a dedicated subfolder ("default/universe_generation" or something like that) and move the universe generation script there (I don't think cluttering the default folder with a load of universe generation Python script files is a particulary brilliant idea
).
Then we can start to break things up into modules. E.g. I'd move the whole star system naming thing in a separate module (maybe "starnames.py"?), and so on.
4.)
Setting module: With modularization in place, I think it would be a good idea to put all "setting" variables like the ones you introduced to control certain aspects of starname generation in a dedicated module ("setting.py") (assuming there might be more of these settings variables to come). That way, we can point anyone who wants to tinker with them to a single location where everything is neatly put together and no other code around confusing people who don't have any clue about programming at all.
Ok, that's my ideas so far. What do you think?