[wiki][Poll] Type naming convention?

[DonQuiche]

Hello everyone. As I explained in another thread, I wrote a bot to automatically generate a full API documentation on the wiki. You can see a sample from an old beta version here. I would like to here your opinion on the naming convention for types. There are two possibilies.

Firaxis style
* "Type" for integers that are issued from the data tables or from enumerations: TerrainType, PolicyType, UnitType, etc.
* "ID" for indexes: CityID, UnitID, etc.

Alternative style
* "ID" for integers that are issued form the data tables or from enumerations: TerrainID, PolicyID, UnitID, etc.
* "Index" for indexes: CityIndex, UnitIndex, etc.


Pros and cons of the Firaxis convention
* The Firaxis convention suits the API naming convention: Plot.SetTerrainType() takes a TerrainType, Unit.GetID() returns an UnitID, etc.
* But it's confusing as hell at the beginning when you realize that "type" does not refer to the "type" column in the database but to the "id" column. Besides their so-called ID are not always global ID: sometimes they are player-specific (two players can use the same ID for two different units), etc.

 

[The_J]

My (unimportant) opinion has not changed since the last time we've discussed it: Firaxis style, just to prevent further confusion between the source files, the API and possibly other modders code.
It's probably easier to explain the obscure thing with the IDs and types once, and make the references consistent to that, than it would be to make the references inconsistent.

 

[Pazyryk]

There's no good solution here. "Firaxis" style is (mostly) consistent with method names but confusing when one is working with ID and Type columns from the database. For my own coding, I use exactly your "Alternate" style (matching database "Type" and "ID" and keeping "Index" for non-DB) because it is much easier on my brain. Civ5 modding is a lot of DB crunching (much more so than Civ4) and it is most important to remember what kind of database element you have in your variable.

Unfortunately, Firaxis Lua code itself doesn't follow either of these styles (or any consistent style at all). Indexed items are usually "iPlayer", "iUnit", etc., but they sometimes use "playerID", "unitID". A variable called "buildingType" has about a 50/50 chance of being either the Type (string) or the ID (integer) from the database.

I haven't voted yet and I'm not sure which way I'll go. I see the value of matching the method names. But I can't stress how important the database is for Civ5 modding, and that is pushing for the "Alternative" (should be renamed "database-friendly") style.

 

[DonQuiche]

As you said, Pazyryk, there is no good solution. Nevertheless, the crowd made a clear and unambiguous choice between Scylla and Charybdis.