0.6 plans

[klauss]

Editing python code to change default settings? Or add presets?

I bet many won't like it. I'm one of that many.
I've seen such complaints when it referred to GUI, mission scripting, campaigns... content people hate code - any kind of code.

[safemode]

the only time you'd need to edit the python is to add a new option not currently handled by the python code.

you wouldn't have to hand edit anything _in any file_

that's why it's got a gui ... any edits go in whatever method of input we provide for that given variable.

When you add a new variable and input method to the config program, you'd set the bounds in the python code (so it can validate user input).

If (_IF_) you want to make a variable enabled by default in the vssetup program, you can hand write it in the defaults.config file, but this would only be done by developers, as users dont add variables to the game.

The heirarchy of variables is preserved in the python code, so when we save the config file, it traverses the enabled options in the gui, and from that, the XML tree is derived and written to a file.

users and "content creators" wont have to edit anything at all by hand. The only people diving into the python or xml code will be developers and modders. Which is exactly the only people who should be diving in.

[safemode]

i think some of the confusion here is in the function of the defaults file.

in my world, the defaults file is optional, it's merely a file to enable some options when the vssetup program is run where no user config file is present.

What dictates what is written to the config file is the python code.

The python code doesn't have presets. It has bounds. Meaning ,the python code has knowledge of all possible values of a given variable, and when no preset is given in xml, it "activates" the first valid value in the bounds. The user is then faced with the decision to change that or leave it via the vssetup gui.

There is no need for anyone not a developer or modder to touch the python code. There is no need for anyone who isn't a developer or modder to touch the defaults.config ... When 0.5.1 is done, there wont be a reason for anyone not a developer or modder to hand write anything in vegastrike.

They wont even need to know what python or xml is.


and by modder, i dont mean an artist adding a unit to see how it looks / works in game, or a person who wants to fidgit with weapons or cargo or stuff, the idea is to make tools for that too. But a modder would be the guy who is customizing config variables for their specific game, they're tailoring the python files to behave the way their mod needs them to. Modders are developers, they just develop in python. That's not who we are talking about when we talk about content creators. Content creators may need to play with csv files (soon with new gui tools) but they dont need to write any python or xml to do that.

The only time you'd need to play with python or xml in my world is if you've added a new config variable to the game and want to expose it to the user or you are a modder who wants to change defaults from vanilla VS or expose more or less variables to the user or simply change the look of the config program to match their mod's feel and function.

[pyramid]

This discussion has developed nicely while I was quietly sleeping

A pic says more than mil words, so maybe an architecture diagram would be in place to provide a basis for further discussion. My current understanding is:

1) You would have a common xml c++ parser, accessible through the vs_config class by vegastrike engine and a new vssetup(python) tool.

2) Through the parser, vs_config would access a game specific default vegastrike.config file and a user.config with the settings changed by the user. The decision what to write where would be handled by vs_config, i.e.
* when vegastrike reads a variable vs_config would first check vsuser.config and if the var was not defined there, get the var from vegastrike.config.
* On the other hand when vssetup is changing the defaults it will write to vsuser.config

Code: Select all

                    vegastrike      vssetup
                             |      |
                              vs_config
                                  |
                            XMLParser
                             |      |
                   vsuser.config   vegastrike.config        

[klauss]

No presets?
Then how would you change from "retro graphics" to "extreme graphics"? It's not a change of one variable but rather a handful.

You can't expose every variable to the user without an easier alternative safemode, they will get a headache!
(I would)

Also some variables are merely for modders and not for end users.

[safemode]

you dont expose the actual variables to the user.

Setting retro mode would enable and disable the appropriate variables.

every gui input is attached to a callback function that handles the setting and unsetting of all the associated variables.

The only thing you have to watch out for is making sure multiple options dont reference the same variable.

Presets can be put in a default.config file, but it's not necessary. It's only necessary when we want to set the "default" config to something that's not the standard default value (all default values for config vars are set via the call to get the variable in the code).
so we'd set some "recommended" values for optimal gameplay and that's it.



basicallly i'm seeing something like this

we have a gui open up when we execute vssetup. Much like the current gui only much more extensive (due to the binding tab and joystick config and some additional options with a button to enable Advanced options).

Each section in the gui has related options grouped together. Some of the options refer to single variables. Some refer to groups of related variables that wouldn't normally be configged individually.

What happens when you save the config is that the save function traverses all of our sections, then traverses down into all of the "activated" sections and pushes all of the "activated" variables. This gets translated to XML via the derived tree produced by traversing the activated options and variables. So what we end up with is a config file consisting only of the variables we have set via vssetup.

So the xml tree is derived, thus it's always correct, always minimalistic and contains no duplications.

[safemode]

I wish i wasn't at work and i could gimp up a diagram of what i'm talking about, plus i'm not sure if you've coded gui frontends before so i dont know what grounds you're refuting the idea on. I've hand coded gtk applications before and the tkinter toolkit isn't very dissimilar.

Much like how vssetup comments blocks of variables, the inputs in the new vssetup would set the xml code variables directly via thier callback functions. These blocks of set xml code are kept in a list of active XML code. This list is what is then traversed by the save function which pushes all the variables into the xml parser which constructs a xml tree from it and writes it to a file.

I'm not sure if i can break it down anymore than that without breaking gimp out and some psuedocode.

Maybe you're getting confused about my bounding in python?

basically every variable in the game has a range of accepted values. Of the variables we choose to put in the config file, we set those accepted values in the python of vssetup, so it can make sure the user doesn't do something stupid. It also works to auto choose defaults in the case that none are read in from the defaults.config file. but it's main purpose is to make sure the user doesn't put anything stupid in.

In no situation does a non-developer/modder need to look at or edit the python or xml files. The only time a developer would poke in the python is when we want to add or remove a config variable to the config file (make it tunable to the user), or if a modder wants to adjust what variables thier mod wants to expose and how they want to expose them to the user.

Everything from the look of vssetup to the function of it would be moddable as it's python. One could even adjust the python script and the main menu to embed configurations into a GL menu. Though, by the time we open gl, we may have to reload the game for some options to take effect. (as they're currently static vars and they are already set).

It's really not complicated. Instead of commenting blocks out, i would use callback functions to push a list (1 or more) of xml statements to a list of activated xml. at the end we push the list to the xml parser, it creates a tree and writes to a file. Simple really.

[klauss]

As long as it's easy to tweak for non-programmers... tweaking presets is very much needed, and non-programmers usually do that. They play with single variables until they find a value that works best.

[safemode]

I dont get what you consider a preset?

if a preset is a default value for a variable, why would a non-programmer need to tweak it? What situation would cause a non programmer to change what the programmer/modder chose as the default? Why if you are tweaking values, would you tweak the default value and not just set a new value via the gui? That sounds like a practice caused by our broken way of doing things currently or we've entered the twilight zone.

If a preset is your way of saying config variable, then changing it's value is no different than putting a new value in it's input area in the gui.

just to be clear:
Modders are developers. Users should never be poking thier noses into xml or python files.

These tools are meant for 3 types of people, they are not meant to be IDE's, though they will help devs. The 3 types of people they are geared towards are end users and non-developers and developers. End users have one tool they need to worry about, vssetup. The other tools are not for them, nor would they ever need to use them.

The other tools, CSV editor (edits our various csv files), and the Universe editor (edits our galaxy/sector/system xml files), are for non-developers to beta test their work. Developers will use these tools to make permament changes to the project.

All the tools would be fully moddable themselves. so that mods can customize the tools to work best with their mod.

[safemode]

If the game has a fully functioning xml parser, why did you say your ogre branch has another one?

Either today or tomorrow, i'm going to look harder at the current xml parser and whatever else at our disposal and decide on which one is ideal based on the following tests.

Does the xml parser allow the direct editing of nodal data. That includes, add, remove, change.

Does the xml parser allow the creation of xml data from strings, files, and write to files. obvious.

Does the xml parser handle user defined types and such (everything we need), so we dont have to hack around it's lack of support.

Does the xml parser require a lot of dependencies, is it easily cross platform and finally, is it efficient.


I can only assume that since we dont edit nodal data in vssetup and friends, that that particular feature is missing from our current in-game xml parser. If that's the case then it's out. Plain and simple, there is no need to have to settle for a half functional xml parser when other better ones exist.

Regardless of the xml backend, the frontend should be the same.

the xml api would be something like this:


// Simple IO
read(string filename)
read(string buffer)
write(string filename)
write(string buffer)

// Modifying and retrieving data
update(string section, string variable, string newdata)
add(string section, string xml)
remove(string section, string variable)
getVariable(string section, string variable, string default)
find(string section, string variable)
clear()

// Statistical info
getNvariables(string section)
getNsections()
getSectionList(string *sections)

// For walking the tree
SetSection(string section)
string * getVariable() // returns array, var and value
string *NextVariable() // returns same unless next is end
string NextSection() // returns name of next section unless at end

// For parsing variable values to real types.
bool parse_bool(string)
int parse_int(string)
float parse_float(string)
double parse_double(string)



Something like that. That would all be under the new class XMLSupport
So whether we use tiny XML, mini-xml or whatever, it should be able to fit into the above api easily and efficiently. And it should be able to pass the tests listed above.

Is there anything missing from the xml api ?

[klauss]

You don't get what presets are.

Developers test VS on, say, a P3 with 256MB ram. They find a ton of tweaks to the config that make it playable. A preset is that ton of tweaks with a name, so vssetup can say "P3 w/256MB ram".

Same goes for graphics, and whatever. Presets are names given to a set of variable changes - a set that developers include in vssetup with the help of non-developer testers. That's why non-developers have to be able to work with that data, to help developers (which usually lack the time to massively test on massive amounts of disparate hardware).

Then you have modders, which may or may not want a GUI for tweaking the internal variables that make the game's content (and hence the mod), and later tell vssetup of all those "different defaults". They're not the defaults in code - a mod shouldn't have to recompile!

Now... about the XML parser... why don't you take a look at XmlDocument?

XMLDocument.h

As you'll see, it does support editing and dumping to a file.
As I said, I wrote it exactly because of that. That, and because I don't like vanilla C mixed with OO C++, so I needed a C++ wrapper to use from within other C++ classes.
And, as I said again, it's just a C++ wrapper of expat (the parser used by VS all over the place).

Note: it may not handle weird encoding mixes, like input that comes in latin-1 and has to be spit out in utf-8. You'll have to provide all utf-8 strings and that kind of stuff. And I don't remember whether it converts some special chars at certain points to entities when writing. But all that can be fixed later.

[safemode]

your main gripe then is that the new vssetup doesn't provide a gui for adding/removing/moving variables in the config file.

That's what we can make the advanced tab do. We can represent the xml tree in a drag and drop editable flat list. With enabled options on the left side of a partititioned window, and disabled options on the right. You can then either drag options over or insert new ones or disable ones manually.

What this will then do is disable "wizard" mode next time you open you config file and it'll open directly in advanced mode.

This is definitely no harder than what such tweakers have to do now with direct xml editing, in fact, that should be quite an improvement.

So vssetup will have wizard mode, (basically looking and working like current vssetup as far as the user is concerned), then an advanced mode that basically exposes all the variables inside our presets directly, including variables not activated and allows the user to arbitrarily add or remove options.

You wouldn't be able to edit such a generated xml config with the stock vssetup in wizard mode however, as it would have conflicting variables with it's "presets", you'd be correctly forced to advanced mode. Eventually a modder could edit the vssetup python and make the new changes defacto.

modders can expose what they want to vssetup, they can make defaults what they want via the defaults.config file. The point i was making was that the existance of a variable in the defaults.config file (or lack of) does not dictate what variables are written to the user config file. vssetup has to be made aware of all the variables you want to find in the user config file that will eventually get written.
But that's pretty obvious.

You dont need to give an input method to all your variables that vssetup knows about and will write to the config file. Most variables will probably not have an associated gui config component.

no recompiling is necessary there.

[safemode]

I like xmldocument.h it has just about everything i had pulled off the top of my head as being a good xml api

couple questions about xmldocument.h

What inherits the classes described in the document? Lots of virtual functions but nothing is immediately shown as inheriting the classes.

I guess that's one question then.

The only things i would want to change about it is removal of the typedefs. It obfuscates and in the end, helps nobody.

The other thing i would change is that I would bring in XMLSupport as the overall api. Where you have 3 classes that function as the abstraction layer over expat's C functions (i take it they are included in the cpp file), I would make a layer that encompasses your 3 classes back down to 1 class that Vegastrike and friends use to actually do all their interfacing with xml documents.

Basically, exposing the functions i listed above from your classes and some native to XMLSupport.


Then as far as python goes, all we have to expose is the XMLSupport class. and as far as development goes, all we have to worry about it the XMLSupport class. Which would have simple straight forward functions and data members.


It's the end of the month and i'm working close to 12 hours a day lately. once june starts i should have much more time to get into the code and see what you're doing over there in your ogre branch. I'll probably want to steal your xml code over to my branch to begin working on the xml api and then begin the userspace helper tools.

I'm gonna try to keep this work out of svn head until it's proven or unless we actually get together and round-table discuss what's going on in the near future.

[klauss]

I like xmldocument.h it has just about everything i had pulled off the top of my head as being a good xml api

What inherits the classes described in the document? Lots of virtual functions but nothing is immediately shown as inheriting the classes.

I have (or had the intention of making) classes that take the xml from something other than files. I also had the intention of adding XML processors for inclusion of external XML, so you could do things as include files and such.

And finally, I've been in the mood for virtual functions lately , turns out that the performance penalty for those is negligible since NetBurst (ya, they did get something right), and they're good OOP practice (dynamic dispatch anyone?)

The only things i would want to change about it is removal of the typedefs. It obfuscates and in the end, helps nobody.

Mind you, they help a lot when you're using the classes. Instead of writing:

Code: Select all

Map<string, Attribute>::iterator

(which, BTW, you have no legal way of knowing that), you write:

Code: Select all

XMLElement::attribute_iterator

(which, BTW, is 10 times more declarative)

Besides, using typedefs abstracts out some implementation details, makes the interface much more (or completely) independent of the underlying implementation.

In essence: get used to them, they're really useful once you get to know them.

I'm gonna try to keep this work out of svn head until it's proven or unless we actually get together and round-table discuss what's going on in the near future.

You know where to find me... right? ( ICQ# )

[safemode]

I want to put the content tools and XML discussion aside for a second and talk about the other thing scheduled (but maybe not listed) for early work in 0.5.x SVN and pkg re-arranging. the reasons are as follows.

1. There is absolutely no reason at all why we should have 3 binary pkgs of over 500MB for 0.5's release. 460MB of each of those pkgs is absolutely unchanged and identical. data4.x needs to be shared, it makes sense to make it shared. It's grossfully inefficient that it's not distributed that way.

2. right now, the svn combines win32 bins into data4.x which for 2 out of 3 majorly supported OS's is unused. This results in wasted hdd space, and much more importantly, wasted SF bandwidth. plus it just doesn't seem right (tm)

So i'd like to discuss a solution.

The first thing we'd do is create 2 new repositories (3 if we insist on making an upstream linux binary). They would be named win32 (not enought people use win64), mac, (linux32).

these repositories would consist of a /bin directory containing the binaries appopriate for that particular OS, then an external definition to data4.x to be pulled alongside it. So an export would produce a filesystem : /vegastrike -> /bin, /data4.x

Now, we'd also have a hq-textures repository that is optional and will sit inside /vegastrike next to /bin and /data4.x

Now, it'd be great to make a python installer that uses svn to pull export (no .svn dirs) repositories so we'd have 1 installer for all os's that can check and update files as needed and do all that work to minimize downloads. That would be the ideal solution to binary distribution, but some people seem to think monolithic single use pkgs are the way to go.

So for those people who insist that pulling from the svn (even though the user would never know it) is too hard for users, I suggest an installer that consists of the /bin of that particular OS and once that's installed, it pulls the data4.x package (it would be archived up separately), during installation. This is no different than how many large scale installations are done. So all the installers would be roughly 40MB (if libs are included), and they'd all share the same data4.x download during installation.

I prefer the svn method. The entire svn process can be hidden behind the (update, install) buttons in the python gui. We can use export and intelligent grepping of svn to determine changed files from one release to the next without having to download full repositories (.svn dirs). The gui can have a button for pulling the hq-textures repository if they choose, and it can have an advanced button to allow a full pull of various branches for part-time developers who are new to svn ...


I imagined the installer to be python based, but if python isn't installed, it may be hard to get an OS agnostic installer working without seperate bins for each os. Maybe forcing users to go install python is good. then we can get away with a single .py file for an installer.

[klauss]

I would also prefer the svn method, but you need monolithic file releases from time to time so that people can "back up" their installers. I do that all the time - I save downloaded installers, in case I loose track of them over the INet or in case I wish to install it on machines without broadband connections (my machine was one such machine when I joined VS!)

However, an svn-pulling script would be very useful for many people. A branch can be kept to the latest (patched) stable release ( branches/stable? ). The script could let you pick one (trunk or stable). It's very useful. That way we could do periodic releases by merging proven changes on the stable branch. Monolithic file releases could be further spaced in time, but they still have a place in my heart

[safemode]

monolithic releases in the sense of how my second idea worked, not in this rather wasteful 3 seperate 500+MB pkgs. this could be done along side of the svn method, since the svn method uses 0 additional space.

So we would push users to the svn method, and give users the ability to pull the pkgs in archive form ... sort of like how distros prefer you to use a minimal install pkg and net-install the rest but also provide dvd iso's ...


And for non-developers, you wouldn't need to pull a whole svn tree to do it, just the exported repositories, so it would take no more space than the traditional pkg. All the svn updating and such can be done via grepping svn remote revisions. and exporting only the changes between them, with no need to compare to a working dir (since we know no changes would have been made locally.

Advanced features would include pulling the full repository, so the user could make changes and operate on their trees via svn directly. This would require double the space than traditional, but allows the user to do everything you'd expect in an svn tree.

I think that aspect is key to the non-svn bin distributers out there. Their main gripe is that the svn pulls would be twice the size or is exported, it would negate the upgrade aspects of svn. Both can be worked around as described above. Plus the svn installer can downgrade seamlessly in the case that an upgrade proves problematic

My main question is how do we want to do the svn installer. We need a minimalist svn client library in python. Then we need to either make python a required dependency or figure out some way of making it work without having 3 separate installers. Though, if we do need 3 separate ones, it wouldn't be _that_ difficult. We'd only need to build it once and forget it, as all functionality would be python

[safemode]

And finally, I've been in the mood for virtual functions lately , turns out that the performance penalty for those is negligible since NetBurst (ya, they did get something right), and they're good OOP practice (dynamic dispatch anyone?)

I consider good oop practices to first include objects as members, then and only if it's necessary, utilize objects by inheritance. It may not be a big deal in real life anymore performance wise, and even if it is, xml is not a fast execution path, but unless there is a really good reason, unecessary processing should be avoided. In your case maybe you're writing a generalized xml library, but in game, we know exactly (or fairly well) what an object will get used for, and we can edit if if that changes. I dont mind the use of virtual in you classes in xmldocument, they seem properly placed for a generalized xml lib intended to be used elsewhere than just vs, and that's fine. But if it were just for vs, i think most if not all would be easily removed as there would be no intention or need for derived classes to change base functionality.

The only things i would want to change about it is removal of the typedefs. It obfuscates and in the end, helps nobody.

Mind you, they help a lot when you're using the classes. Instead of writing:

Code: Select all

Map<string, Attribute>::iterator

(which, BTW, you have no legal way of knowing that), you write:

Code: Select all

XMLElement::attribute_iterator

(which, BTW, is 10 times more declarative)

Besides, using typedefs abstracts out some implementation details, makes the interface much more (or completely) independent of the underlying implementation.

In essence: get used to them, they're really useful once you get to know them.

my disdain for typedefs comes form what we do with Vector. That's a cluster F caused by someone's hatred or complete lack of understanding that templates exist in C++. Typedef is obviously not all bad, but if it's just done to make something easier to type with then it's wrong. If it's there to make the API complete, then that's fine.

basically, your public typdefs are fine, as they separate private data types from public, making the api cleaner.

The private typedefs are what I disagree with. They only serve to make your immediate life easier, and prove to only obfuscate the code for people coming after you to maintain the code. You may have made it less obfuscated by putting it all out in the open in one place, but it's obvious that private typedefs only serve to make the original writer's life easier by reducing how much they had to type for a datatype.

That's my objection anyway.

I'm gonna try to keep this work out of svn head until it's proven or unless we actually get together and round-table discuss what's going on in the near future.

You know where to find me... right? ( ICQ# )

I'm sure i can find it but i dont have an account with icq. I would prefer IRC as it doesn't require signing up for anything, and it's easy to get a realtime discussion among many people, and you can see a backlog of conversation when you're not around. I'm sure most are familiar with how irc works, I just dont understand how people can utilize instant messaging systems but are somehow unable to access irc.

[klauss]

And finally, I've been in the mood for virtual functions lately , turns out that the performance penalty for those is negligible since NetBurst (ya, they did get something right), and they're good OOP practice (dynamic dispatch anyone?)

I consider good oop practices to first include objects as members, then and only if it's necessary, utilize objects by inheritance. It may not be a big deal in real life anymore performance wise, and even if it is, xml is not a fast execution path, but unless there is a really good reason, unecessary processing should be avoided.

Well, I did say I intended to override base functionality in some cases (reading from Ogre Resource s, for instance).

The private typedefs are what I disagree with. They only serve to make your immediate life easier, and prove to only obfuscate the code for people coming after you to maintain the code. You may have made it less obfuscated by putting it all out in the open in one place, but it's obvious that private typedefs only serve to make the original writer's life easier by reducing how much they had to type for a datatype.

I dont't think there's much obfuscation. I define an ElementList as that - a container of elements. Whatever implementation is behind it doesn't matter, one knows it's a container of elements. Hence the typedef. If at some point I decide to change the vector<XMLElement> to list<XMLElement> it's a one-line change, rather than a gazillion-line one (one for each time an iterator has to be used, for instance).

You're right, it's there to make my life easier, but isn't that true for any programming language above assembly?

Perhaps you'd like it better if it was defined in the .cpp, but sadly C++ doesn't allow that (I think), without seriously weird stuff - weird stuff I'm doing in Audio classes, BTW. But there it's justified because the structures I use in the implementation side really really should be left to the .cpp and not exposed in the interface (ffmpeg structs, for example).

I'm sure i can find it but i dont have an account with icq. I would prefer IRC as it doesn't require signing up for anything, and it's easy to get a realtime discussion among many people, and you can see a backlog of conversation when you're not around. I'm sure most are familiar with how irc works, I just dont understand how people can utilize instant messaging systems but are somehow unable to access irc.

I just never found an IRC client to my liking. I've always felt uncomfortable using IRC channels, probably because of the client and not the protocol/idea. Though I did recently discover Pidgin's IRC support (I never tried it though).

[safemode]

first of all, it's private, so it's only going to be used in that one object. So there isn't a whole lot of changing you need to do. This inconvenience is offset by the readily apparent nature of the variable.

This is completely different from public typedefs. public typedefs operate as an api. Private data members are not part of any api. Your hiding datatypes behind smaller words only serves to create a small convenience at the expense of obfuscating the type. And the type is extremely important in the cases where anyone would be diving into the implementation to work on the code. Unlike the type of the public members which should be of no consequence to users of the public members.


This is about making people's lives easier who want to rework the implementation without having written it from scratch, not people who want to use the code. You're right that typedefs hide the gritty details of the workings of a data member, and it makes it easy for everyone to use the deeper datatypes, but by that same token, someone working in the implementation _WANTS_ to know the deeper datatype and they dont care about some typedef'd meaningless datatype.

the code should be written so maintenance is easy for someone coming in not knowing what is going on, not so it's easier for someone who knows the code in and out to play with it.

I think it's acceptable to use typedefs as means for API separation, and it's likely that such uses are necessary when they depend on internal implementation details. We want the api's to be stable.

I dont think it's acceptable to use typedefs within the implementation in a private manner not associated with the api separation. And my reason is the same as why it's good, it hides the implementation details. The difference is, when a programmer dives into the implementation files, he _wants_ to know the implementation details. Typedefs hide that, thus they're not welcome there.



if you find that you need to substitute a datatype for another, most editors have a replace button that will let you replace all instances matching X. and that is perfectly usable any situation where you'd have been using the true datatype rather than a typedef.

[klauss]

Ok, this is deriving into a phylosophical debate.

So... phylosophical issues aside, I precisely wrote those typedefs because they made my life easier in many levels. Presumably, those working on the code, once they take the small effort it takes to read what the type is (which is there on the name: ElementList, AttributeMap), they know how to use it. If all they want is write code using it, it's enough. If they want to change it, there's only one place to change it, rather than many.

Search and replace won't work.

Non-real-world example:

Code: Select all

typedef map<string,string> AttributeMap;
typedef map<string,string> ElementIndex;

They underlying type is the same - the usage is different. If I want to change the ElementIndex to the more useful:

Code: Select all

typedef map<string, ElementList::iterator> ElementIndex;

Then I cannot (with search and replace).

Let me repeat myself, only to make my point clear. I respect your point of view, and you can do whatever you want with the code, it's opensource. I just want you to know the reason behind those typedefs, maybe just maybe you'll find a light at the end of that tunnel:

I did it because it makes the code easier to read and to mantain.

[safemode]

I'm working from the point of view that not everyone is going to name their typedefs after the source datatype.

elementList refers to a list::iterator
elementMap refers to a map<whatever,whatever>::iterator

that's fine and completely understandable and it does everything you say it does.

now what happens when you make ElementList into a vector. or some other datatype. Now it's named ElementList, and you chose list because it refers to std::list which is what you originally used but now it's not. Now the name is as meaningless as anything else. Now fast forward 2 years and after X number of changes nobody has a damn clue what ElementList is because it's a typedef of a typedef in another source file set by a Macro and come runtime nobody can figure out what it is.

Your purpose only works if nobody changes the datatypes behind the typedefs. After that, it becomes just as obfuscated as anything else typedef'd to some completely unrelated name. And if nobody is going to change the datatype, then the use of typedef in the first place is gone.

You're making a black box within the implementation, not to protect an api, but to make it easy for someone who knows what's in the black box. That's the light at the end of the tunnel. It's not that your use of it is hard to understand and follow, it's that allowing that type of use of typedefs will find it's way to large classes (caugh, unit, caugh) where it most certainly will become very hard to understand. And that's just gen 1, in the future it'll be damn near unfollowable.


edit: BTW, i'm glad you're actually arguing back and showing an interest. Some of us are trying to bring structure to the (some parts) mess that has become of nearly a decade of working on top and around spliced and hacked code. It's hard to do that when nobody else cares. I think we're getting somewhere, i'm just unconvinced that this convenience wont be used for evil in much larger and complex classes than this simple xml example. Think Unit. etc. You coded xmlDocument extremely well and neat, so it's a bad example of poor code practices, but obviously, you didn't and aren't going to code the rest of VS. and the underlying principal of what i'm suggesting applies to your nice and proper code as it would the rest. Overall it seems to me that the ends justify the means, and the means being some inconvenience writing the code for the convenience of being able to read and work on it not having written it.

[chuck_starchaser]

elementList refers to a list::iterator
elementMap refers to a map<whatever,whatever>::iterator

that's fine and completely understandable and it does everything you say it does.

now what happens when you make ElementList into a vector. or some other datatype.

But, Safemode, you're giving a text-book case of bad naming. That's worse than bad naming; it's EVIL naming. If anything, the name should be "Elements". It's not the client's business whether the elements are in a list or a vector. Names should be concise, and only express what something is at the highest possible level, from a client's perspective. Adding "List" to the name is unnecessary, verbose, misguided, and as you point out, dangerous.
But if it refers to an iterator, the name should really be "ElementsIterator".

[safemode]

i didn't give it that name. The point was being made that the name was descriptive to the hidden type, thus it wasn't obfuscating. I made the point that the typedef was there to hide the implementing type so that the implementing type could be changed without changing all it's uses individually, and that if it ever was changed, the name wouldn't reflect the hidden type. Thus the name offered no help in not obfuscating the hidden type.

The whole point of all that was that there is no client code here. These are private variables.

Everyone agrees that api's should hide implementation from clients, that's fine. But since there is no client in private land, none of that applies.

[klauss]

No no... chuck has it right. The intent of naming it "List" was to make sure it was a collection of elements. A back-appendable collection at least, I believe. You know, the STL has those concepts of back-appendable, ordered, unordered container, blah blah...

The intent was to put in evidence its collection properties, not the type. Maybe I made a mistake by using "List" as a suffix. The "s" seemed too small and unclear, thoguh. I did consider using "Elements", but seemed prone to generating confusion. A poor choice.

You could rename it if you think it would solve the problem. And I'll try to use whatever naming scheme seems more suitable.

BTW: Same goes for the Map. Map stands for "mapping" - the concept of map, not the datatype itself.