The International Simutrans Forum

 

Author Topic: Preferred variable names  (Read 13427 times)

0 Members and 1 Guest are viewing this topic.

Offline Ters

  • Coder/patcher
  • Devotee
  • *
  • Posts: 5454
  • Languages: EN, NO
Preferred variable names
« on: October 21, 2013, 03:37:42 PM »
With the translations from German to English, we need to fix up the preferred variable name section in the coding style:
 
At the moment, it is as follows:
 
Loop counters (int)i, j, n
Indices (int)i, index, n
Coordinatespos (position), k (arbitrary coordinate)
Screen positionsx, y (short form), xpos, ypos (long form, preferred)
Convoicnv
Vehiclesv
Rail signalssig
Rail blocksbs (obsolete)
Groundsgr (often also bd (from boden))
Roadsstr
Railroadssch
Generic wayweg
Buildingsgb
Factoriesfab
UI componentskomp, c (temporary component variables) seldom directly used
UI windows? ? ? (win is preferred)
UI eventsev
Buttonbutton
Button lists/vectorsbuttons
Scrollable listscl
Temporary int valuet
Temporary char valuec
Temp. general valuetmp
Temporary resultr, res, result ('result' is preferred)

I suggest (unmodified are filtered out):
 
Coordinatespos (position), c/coord (arbitrary coordinate)
Groundsgr
Roadsroad
Railroadsrail
Generic wayway
Buildingsbld?
Factoriesfac
UI componentscomp, c (temporary component variables) seldom directly used
UI windowswin
c is used for several things, both originally and even more in my suggestions. Maybe it should be dropped for coordinates and components, but on the other hand, ch is also a more familiar abreviation of character. (Strictly speaking, character doesn't start with a c-sound, but a ch-sound.)

Offline kierongreen

  • Dev Team, Coder/patcher
  • Devotee
  • *
  • Posts: 2269
Re: Preferred variable names
« Reply #1 on: October 21, 2013, 04:00:24 PM »
komp -> comp should only happen when komponent becomes components. That'll be a big patch!

Likewise until koord becomes coord we should stick with k for coordinates (another big patch).

gb for buildings is used a lot - even 3 letters could add considerably to line length. I would suggest either bd (if bodens are removed) or possibly just b. Also as above this change should only happen when gebaude becomes building.

gr (only) for ground is ok - just have to watch out because often bd is used in same section of code at the moment.

fac(tory), rail(way), road(s), (generic) way all seem fine.

Offline Ters

  • Coder/patcher
  • Devotee
  • *
  • Posts: 5454
  • Languages: EN, NO
Re: Preferred variable names
« Reply #2 on: October 21, 2013, 04:21:11 PM »
It's a list of preferred names, so whatever we decide will be the preferred names for when the translation eventually happens.

gr is by the way already listed as preferred, I just deprecated bd even more.

Offline prissi

  • Developer
  • Administrator
  • *
  • Posts: 9438
  • Languages: De,EN,JP
Re: Preferred variable names
« Reply #3 on: October 21, 2013, 07:36:49 PM »
bd and gr is probably from very old ages, when bd was not neccessary a ground (i.e. grund_t did what planquadrat_t t did). At least one very early sketch of Hajo did indicate this. So maybe first a patch bd=>gr is in oder.

That str for street is ratehr lucky coincidence, as it was strasse_t ...

Offline Ters

  • Coder/patcher
  • Devotee
  • *
  • Posts: 5454
  • Languages: EN, NO
Re: Preferred variable names
« Reply #4 on: October 21, 2013, 08:47:54 PM »
That str for street is ratehr lucky coincidence, as it was strasse_t ...

Except that in modern English street only applies to roads in an urban setting (according to Wikipedia).

Offline prissi

  • Developer
  • Administrator
  • *
  • Posts: 9438
  • Languages: De,EN,JP
Re: Preferred variable names
« Reply #5 on: October 21, 2013, 09:07:44 PM »
vehicle is certainly not common, same for convoi ... and unlike sch for schiene str for road makes some sense.
But road and rail are obviously better.

Offline jamespetts gb

  • Simutrans-Extended project coordinator
  • Devotee
  • *
  • Posts: 18502
  • Cake baker
    • Bridgewater-Brunel
  • Languages: EN
Re: Preferred variable names
« Reply #6 on: October 25, 2013, 12:09:23 AM »
How about welt/world; and also plan/grid_tile?

Offline Ters

  • Coder/patcher
  • Devotee
  • *
  • Posts: 5454
  • Languages: EN, NO
Re: Preferred variable names
« Reply #7 on: October 25, 2013, 04:44:02 AM »
Do we have any non-grid tiles?

Offline kierongreen

  • Dev Team, Coder/patcher
  • Devotee
  • *
  • Posts: 2269
Re: Preferred variable names
« Reply #8 on: October 25, 2013, 07:08:47 AM »
grid_tile was the best name I could think of for planquadrats, as opposed to terrain for boden/grund. Unless you have different suggestions?

Offline Dwachs

  • DevTeam, Coder/patcher
  • Administrator
  • *
  • Posts: 4564
  • Languages: EN, DE, AT
Re: Preferred variable names
« Reply #9 on: October 25, 2013, 08:50:56 AM »
In the squirrel interface I named the equivalences of grund_t and planquadrat_t tile and square. A planquadrat is internally just a stack of tiles.

Offline prissi

  • Developer
  • Administrator
  • *
  • Posts: 9438
  • Languages: De,EN,JP
Re: Preferred variable names
« Reply #10 on: October 25, 2013, 09:05:54 AM »
Although ground_t would make sense since we had lots of gr all over the code ...

plaquadrat: square comes close to the german word indeed. But I am slightly biased towards grid_t (or probably grid_square_t), since square is very close to tile (both are more or less 2D in my imagination).

But a god part of planquadrat is anyway left over from the times when you had to lookup the ground yourself. There is certainly potential in cleaning up lurking and switch to ground_t in some places.

Offline jamespetts gb

  • Simutrans-Extended project coordinator
  • Devotee
  • *
  • Posts: 18502
  • Cake baker
    • Bridgewater-Brunel
  • Languages: EN
Re: Preferred variable names
« Reply #11 on: October 25, 2013, 12:36:41 PM »
"grid_square_t" seems probably the clearest, I think. "ground_t" also seems quite clear.

Offline Ters

  • Coder/patcher
  • Devotee
  • *
  • Posts: 5454
  • Languages: EN, NO
Re: Preferred variable names
« Reply #12 on: October 25, 2013, 03:59:36 PM »
A planquadrat is technically more of a column than a square, but I don't think that matters much.

As for ground_t, I find that a more suitable translation for boden_t, based on the description for boden_t. However boden_t's position in the class hierarchy doesn't quite fit that description.

Offline VS

  • Senior Plumber (Devotee)
  • Devotee
  • *
  • Posts: 4855
  • Vladimír Slávik
    • VS's Simutrans site
  • Languages: CS,EN
Re: Preferred variable names
« Reply #13 on: October 25, 2013, 05:43:51 PM »
planquadrat = tile ?

Offline Dwachs

  • DevTeam, Coder/patcher
  • Administrator
  • *
  • Posts: 4564
  • Languages: EN, DE, AT
Re: Preferred variable names
« Reply #14 on: October 25, 2013, 05:45:45 PM »
planquadrat = tile ?
No, internally not: a tile (i.e this diamond shape area you can build tracks on) is currently called grund / boden = ground.

Planquadrat are all tiles on a particular 2d-spot: all tiles sharing the same (x,y) coordinate.

Offline prissi

  • Developer
  • Administrator
  • *
  • Posts: 9438
  • Languages: De,EN,JP
Re: Preferred variable names
« Reply #15 on: October 25, 2013, 08:14:52 PM »
boden is indeed some kind of ground too, but it is ground with some grass. Maybe call it soil_t to differenciate from bridges, tuneels, fundations, and elevated grounds. Or base_ground_t and elevated_ground_t ... (instead monorailboden_t)?

Offline Ters

  • Coder/patcher
  • Devotee
  • *
  • Posts: 5454
  • Languages: EN, NO
Re: Preferred variable names
« Reply #16 on: October 25, 2013, 09:09:49 PM »
boden is indeed some kind of ground too, but it is ground with some grass. Maybe call it soil_t to differenciate from bridges, tuneels, fundations, and elevated grounds. Or base_ground_t and elevated_ground_t ... (instead monorailboden_t)?

Part of my point was that bridges and tunnels inherit from "soil_t" (boden_t), which doesn't seem right as far as the names go. In terms of the code, it might make sense, but complicates intuitive naming. tunnelboden and brueckenboden could be tunnel_floor and bridge_deck in English code.

Offline isidoro

  • Devotee
  • *
  • Posts: 1128
Re: Preferred variable names
« Reply #17 on: October 26, 2013, 12:39:30 AM »
If a planquadrat represents a pile of tiles or a pile of grounds, why not just call it PileOfXxx?

Offline jamespetts gb

  • Simutrans-Extended project coordinator
  • Devotee
  • *
  • Posts: 18502
  • Cake baker
    • Bridgewater-Brunel
  • Languages: EN
Re: Preferred variable names
« Reply #18 on: October 26, 2013, 10:42:49 AM »
If a planquadrat represents a pile of tiles or a pile of grounds, why not just call it PileOfXxx?

I think, strictly, it does not represent a pile (i.e., set) of points in three dimensional space, but rather a single square in two dimensional space, so this would not be accurate.

Offline prissi

  • Developer
  • Administrator
  • *
  • Posts: 9438
  • Languages: De,EN,JP
Re: Preferred variable names
« Reply #19 on: October 27, 2013, 10:00:29 PM »
Hmm, boden seem some of the few more universal german word than its english counterpart.

Hence I would suggest, then just have ground variants: ground_t (the origin) which goes to map_ground_t, bridge_ground_t, elevated_ground_t, foundation_ground_t (or even house_ground_t), and tunnel_ground_t. Not gramatically very beautiful, but at lest consistent. The biggest disadvantage is that map_ground_t is much longer than boden_t.

Offline kierongreen

  • Dev Team, Coder/patcher
  • Devotee
  • *
  • Posts: 2269
Re: Preferred variable names
« Reply #20 on: October 27, 2013, 10:15:09 PM »
or maybe plan goes just to grid, then boden... to tile, bridge_tile, elevated_tile, tunnel_tile, foundation_tile?

Offline Ters

  • Coder/patcher
  • Devotee
  • *
  • Posts: 5454
  • Languages: EN, NO
Re: Preferred variable names
« Reply #21 on: October 28, 2013, 05:41:57 AM »
Hmm, boden seem some of the few more universal german word than its english counterpart.

Hence I would suggest, then just have ground variants: ground_t (the origin) which goes to map_ground_t, bridge_ground_t, elevated_ground_t, foundation_ground_t (or even house_ground_t), and tunnel_ground_t. Not gramatically very beautiful, but at lest consistent. The biggest disadvantage is that map_ground_t is much longer than boden_t.

map_ground_t is a bit odd, but apart from that, it works. I'd probably keep house_ground_t for the requested feature if building on top of other buildings, not that that feature is too likely.

or maybe plan goes just to grid, then boden... to tile, bridge_tile, elevated_tile, tunnel_tile, foundation_tile?

grid on it's own won't work, as that's descriptive for the entire map. It would have to be something like grid_square. By dropping grid, we're then at what Dwachs wrote that the scripts use, which isn't a bad place to end up. There is still the question that if boden becomes tile, what does grund become? Having tile be a form of ground doesn't sound right to me. The other way around seems better, but bridge_tile is a better name than bridge_ground.

Offline prissi

  • Developer
  • Administrator
  • *
  • Posts: 9438
  • Languages: De,EN,JP
Re: Preferred variable names
« Reply #22 on: October 28, 2013, 09:19:12 AM »
I think it would make sense to keep ground for grund to do not alter all the gr in the code.

But the idea with tile seem reasonable (and shorter): ground_tile, bridge_tile, house_tile, tunnel_tile, water_tile, elevated_tile. Soundsok, especially water_tile is better than water_ground ...