Author Topic: Preferred variable names  (Read 8706 times)

0 Members and 1 Guest are viewing this topic.

Offline Ters

  • Coder/patcher
  • Devotee
  • *
  • Posts: 4812
  • Total likes: 191
  • Helpful: 108
  • 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

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: 4812
  • Total likes: 191
  • Helpful: 108
  • 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: 8798
  • Total likes: 319
  • Helpful: 229
  • 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: 4812
  • Total likes: 191
  • Helpful: 108
  • 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: 8798
  • Total likes: 319
  • Helpful: 229
  • 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

  • Simitrans-Extended project coordinator
  • Devotee
  • *
  • Posts: 15697
  • Total likes: 395
  • Helpful: 174
  • 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?
Download Simutrans-Extended.

Want to help with development? See here for things to do for coding, and here for information on how to make graphics/objects.

Follow Simutrans-Extended on Facebook.

Offline Ters

  • Coder/patcher
  • Devotee
  • *
  • Posts: 4812
  • Total likes: 191
  • Helpful: 108
  • 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

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: 4247
  • Total likes: 175
  • Helpful: 149
  • 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.
Parsley, sage, rosemary, and maggikraut.

Offline prissi

  • Developer
  • Administrator
  • *
  • Posts: 8798
  • Total likes: 319
  • Helpful: 229
  • 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

  • Simitrans-Extended project coordinator
  • Devotee
  • *
  • Posts: 15697
  • Total likes: 395
  • Helpful: 174
  • 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.
Download Simutrans-Extended.

Want to help with development? See here for things to do for coding, and here for information on how to make graphics/objects.

Follow Simutrans-Extended on Facebook.

Offline Ters

  • Coder/patcher
  • Devotee
  • *
  • Posts: 4812
  • Total likes: 191
  • Helpful: 108
  • 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: 4849
  • Total likes: 25
  • Helpful: 63
  • 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 ?

My projects... Tools for messing with Simutrans graphics. Graphic archive - templates and some other stuff for painters. Development logs for most recent information on what is going on. And of course pak128!

Offline Dwachs

  • DevTeam, Coder/patcher
  • Administrator
  • *
  • Posts: 4247
  • Total likes: 175
  • Helpful: 149
  • 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.
Parsley, sage, rosemary, and maggikraut.

Offline prissi

  • Developer
  • Administrator
  • *
  • Posts: 8798
  • Total likes: 319
  • Helpful: 229
  • 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: 4812
  • Total likes: 191
  • Helpful: 108
  • 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

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

  • Simitrans-Extended project coordinator
  • Devotee
  • *
  • Posts: 15697
  • Total likes: 395
  • Helpful: 174
  • 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.
Download Simutrans-Extended.

Want to help with development? See here for things to do for coding, and here for information on how to make graphics/objects.

Follow Simutrans-Extended on Facebook.

Offline prissi

  • Developer
  • Administrator
  • *
  • Posts: 8798
  • Total likes: 319
  • Helpful: 229
  • 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

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: 4812
  • Total likes: 191
  • Helpful: 108
  • 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: 8798
  • Total likes: 319
  • Helpful: 229
  • 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 ...