The International Simutrans Forum

Development => Patches & Projects => Larger Projects => Topic started by: felo on March 10, 2010, 05:48:22 PM

Title: German in the code
Post by: felo on March 10, 2010, 05:48:22 PM
Excuse my English

[EN]
It would be recommended that the comments, functions and variable names were in English. The German language keeps many people out of the code, I went mad because of dings, Ribi, etc.
A search and replace would help much, at least with the names of functions and variables.

[ES]
Sería recomendable que los comentarios, nombres de funciones y variables estuviesen en ingles. El alemán mantiene a muchos fuera del código, ya me tiene medio loco los dings, ribi, etc.
Una búsqueda y reemplazo ayudaría mucho, por lo menos en los nombres de funciones y variables.
Title: Re: German in the code
Post by: IgorEliezer on March 10, 2010, 06:18:01 PM
Excuse my English

No need for excuses, your post is understandable. I did some edits so people won't have doubts about what you meant. ;)
Title: Re: German in the code
Post by: prissi on March 10, 2010, 09:13:11 PM
ribi is not german either. It is just an artificial word form (Richtungs bits, aka english dibi from direction bits [so no improvement in english]). But you know, renaming everything would make nearly all patches useless ...

Whenever there is some renovation, we renamed some variables. But since the team size is that small, any additional work is not warmly embrassed. Also many of the active developers were german, the only notable contributions from the non-german region were from kierongreen, Timothy, Knightly and z9999. It has also not stopped jamespett to branch into the experimental branch. Incidentally, this is not too different from TTDpatch, thus aparently german programmers have a liking to transportation games ...

You are welcome to do a patch to translate everything. Or add documentation. I do it, whenever we touch something old. But many parts are stable and thus I do not touch them.

Imho the biggest problem with a big projekt is, simply it is big. Even though simutrans is quite strongly modulized due to heavy OOP usage, most thing that can be achieved by a simple change have been already done. And for advanced stuff you need to dig into the code for a month or so to get an idea, imho. Perhaps ask Knightly or Dwachs about it, since those joined the team more recently.
Title: Re: German in the code
Post by: jamespetts on March 10, 2010, 09:18:18 PM
I found Google Translator very helpful in deciphering German variable names. I understand the problems with translating the names, but perhaps there should be at least a concerted effort to put English translations into the code comments? That's what I do whenever I translate something for Experimental.
Title: Re: German in the code
Post by: Amelek on March 10, 2010, 09:37:02 PM
amount of work required to translate code from German to English seem unimaginable. For instance, I attach patch that fixes "welt" and "Welt" to "world" and "World".

http://mallorn.ii.uj.edu.pl/~amelek/WeltToWorld.zip

877 kb unpacked patch file...

and obviously, some comments got messed up
Title: Re: German in the code
Post by: wlindley on March 10, 2010, 10:09:18 PM
Maybe a "Rosetta Stone" or "abbreviations/translation table" file, instead of trying to rewrite everything.
Title: Re: German in the code
Post by: felo on March 10, 2010, 10:18:03 PM
[EN]
It not seems so complex.
In the Visual Studio you can use the tool 'Replace in files', choose these options appropriate and replace all occurrences of a word in all files of the solution.

On the prevalence of German programmers think is partially due to this problem. Due to the size of the project is very difficult to understand the code and many give up.

Much of the time I lose in translating and find where things are, no doubt that ultimately succeeds in doing something but by that time I have learned a few words in German.

In addition there are almost no comments. If you could put a comment at the beginning of each file explaining that thing would help a lot.

[ES]
No me parece tan complejo.
En el Visual studio se puede usar la herramienta 'Replace in files', seleccionar las opciones adecuadas y reemplazar de un golpe todas las ocurrencias de una palabra en todos los ficheros de la solución.

Sobre la prevalencia de los programadores alemanes pienso se deba en parte a este problema. Por el tamaño del proyecto se hace muy difícil entender el código y muchos desisten.

Gran parte del tiempo lo pierdo en traducir y encontrar donde están las cosas, no hay dudas que al final se logra hacer algo pero para ese momento ya he aprendido unas cuantas palabras en alemán.

Además casi no existen los comentarios. Si se pudiera poner un comentario al principio de cada fichero explicando que cosa es, ayudaría mucho.
Title: Re: German in the code
Post by: prissi on March 10, 2010, 10:34:54 PM
Simutrans is not that badly commented. Try out OpenTTD for a change ... (maybe the had improved meanwhile, but the last time I checked it was rather pages without comments at all.)

Commenting each file what it does would be nice, but I still have to see a real world project of similar size where this had been done and those header are still correct. Simutrans stems from a hobby project of Hajo (german) who tried himself to self study C++ by writing a program.

And you are right, there are tools that could do that. And all of them usually fail since simple searching and replacing does not always do the trick or a file is omitted. And it breaks all patches, which makes a lot of additional work.

Moreover, the function of an object is not dependent on the naming. If you have an idea, what dingliste_t does, I doubt you would have a different idea what thinglist_t or mononolisto_t would do. I had even a mathematic teacher who deliberately chose wierd names for variables to avoid to connect wrong ideas to the meanings for them.

If you consider to work on the code, just ask. This is usually 99% more helpful than searching through the code, because we can give answers like: "Drawing is done in simview.cc, which calls display_xxx from grund.cc and simplan.cc" Even with extremly well comments, figuring this out would have taken you longer than just asking.
Title: Re: German in the code
Post by: felo on March 10, 2010, 10:52:32 PM
[EN]
Well. I'll Ask.

About the patches, I don't know how they work.

[ES]
Bien. Preguntaré.

Sobre los parches, no se como funcionan.
Title: Re: German in the code
Post by: kierongreen on March 11, 2010, 07:53:46 AM
I've certainly found language is a fairly minor obstacle when it comes to contributing to the code. For someone new to the code even knowing where abouts a particular change might have to be made could take several hours to work out due to the shear amount of code there, in comparison working out what a comment means (I only have rudimentary German, so might rely on google translate for some things) really doesn't take too long. The common variable and function names you pick up very, very quickly!
Title: Re: German in the code
Post by: Spike on March 11, 2010, 09:08:30 AM
I had a slow migration to English names and comments in mind when the project started to be more than my personal toy. But as others pointed out, that was and still is quite difficult in some areas.

But I think we should still try to get there ... all new code should be English and all new comments, too. Samewise, changed code should be changed to English where possible, and changed comments, too. This way the code should become more international step by step.

I'm sorry for all the German in the code. It's been my only project where I used German for identifiers and comments, and just this one became popular enough that others wanted to participate ... bad luck :( In the beginning this was really just a personal toy project of mine.

Having said that, the one who wants to try a full translation of code and comments has my full support!

Title: Re: German in the code
Post by: neroden on March 22, 2010, 12:48:43 AM
I had a slow migration to English names and comments in mind when the project started to be more than my personal toy. But as others pointed out, that was and still is quite difficult in some areas.

But I think we should still try to get there ... all new code should be English and all new comments, too. Samewise, changed code should be changed to English where possible, and changed comments, too. This way the code should become more international step by step.

As a comment on priorities, I think full-length German words (Welt, Ding, Fabrik, Stahl, Weg, keine, etc.) aren't that much of a problem as they can be looked up in a dictionary or using Google Translate.

German *abbreviations* are confusing ("wkz", "ribi", "koord"); mixed language is confusing; ("has_diagonal_bild" -- should be has_diagonal_picture or hat_bild_diagonale, surely?) and in general abbreviations are very confusing ("get_wtyp")?  If anyone plans to do piecemeal change I suggest focusing on these.
Title: Re: German in the code
Post by: prissi on March 22, 2010, 08:58:20 PM
Well get_ was gib_ before. Thus this is the result of automatic changing of the code as requested earlier.
Title: Re: German in the code
Post by: Spike on August 01, 2010, 11:05:37 AM
Someone, I think Neroden, undertook a change to split gui_koord from koord. Maybe this new type can be named gui_coord, to be closer to English in the spelling?

Also, koord could be renamed to coord, (or point or point_t  maybe?) after the split.

Nothing serious, just suggestions to move to a more English codebase if things are in works anyways.

wkz_ could become tool_.
Title: Re: German in the code
Post by: TurfIt on January 08, 2012, 07:59:02 PM
Splitting the German discussion back out of the oneway roads implementation thread...
If you mean the German comments, sure. If you mean renaming variables, to what end? IMO they're fine as is.
I still haven't sorted back out the half-assed renaming of einstellungen to settings... Now instead of just einstellungen and umgebung to keep straight, we get a third one (settings) to remember.
But I surely have more chances to understand a Chinese person walking down the street than einstellungen or umgebund.  Let's be serious...  If a certain translation was not completely accomplished, it doesn't mean that translation is not needed and have not been asked for several times from different people.

 If we want to favor a truly open development project, German is a serious issue.  Another thing is if we want to keep it for a more reduced set of developers.  But that is not a good strategy, imho.  You shouldn't be afraid of opening it.  What goes or not to the trunk is still a decision of head developers.  And if somebody comes and doesn't agree, all he has to do is a fork.  And time will tell who were right.
Reply #9 above by kierongreen I think hits the nail on the head. The German in the code is insignificant compared to learning the code itself. If ones language skills are so bad that it's an obstacle, then I wonder if that translates to their programming language skills too, and hence it's probably best if they didn't try contributing...

Also, I'm actually finding the German identifiers to be helpful! I can do a translation (I highly recommend dict.cc for this purpose), and pick one of the many synonyms that *I* think fits the usage best. Yes, sometimes I pick wrong and have to go back and change my pick, but still easy. If instead, everything was in English, them I'm stuck using the word that the original programmer chose. Perhaps that word is not the best fit for the usage; With the prevalence of non-native English speakers contributing, the odds of the 'wrong' English word being chosen are much higher.
Title: Re: German in the code
Post by: Spike on January 08, 2012, 09:03:20 PM
I'm used to Java development environments, and they make renaming variables quite easy. Place cursor on variable name, hit rename hotkey, enter new name. The IDE will replace all occurrences and usages of the variable with the new name. And only the variable, no other text containing the string.

I would expect that C++ IDEs can do that too?
Title: Re: German in the code
Post by: prissi on January 08, 2012, 09:20:07 PM
It depends, as there are not all files in a project. And the makeobj does some dirty tricks which C++ IDE may thing certain files were not used, as they are only bound together during link time.
Title: Re: German in the code
Post by: jamespetts on January 08, 2012, 09:24:03 PM
It depends, as there are not all files in a project. And the makeobj does some dirty tricks which C++ IDE may thing certain files were not used, as they are only bound together during link time.

Can't one just (1) include those files into the project where possible (as "external resources" if they should not be compiled); or (2) make a list of all the variable names in these external files if that is not possible, and replace them with a straight search-and-replace on those documents, or manually, if necessary, using the standard method for anything not in those files?
Title: Re: German in the code
Post by: TurfIt on January 08, 2012, 09:41:25 PM
variable name, hit rename hotkey, enter new name. The IDE will replace all occurrences and usages of the variable with the new name. And only the variable, no other text containing the string.
Which is rather the problem.
Code: [Select]
    const weg_t * weg = gr->get_weg(get_waytype());
needs to end up
Code: [Select]
    const way_t * way = gr->get_way(get_waytype());
 
else everything will quickly become incomprehensible.

Also all the abbreviations (and possible inconsistent uses thereof) need to be changed too.
What is 'gr' above. Usually a grund_t. But I've seen bd used as a grund too rather than a boden.
And str is usually for strasse_t but used someplaces as a weg_t. And these are the easy cases to find the abbreviation where the first parts of the english and german words overlap. For the rest?? ?

There's already a complaint above about the results of search/replace... best not to compound things further confusing everybody just become some are too lazy to consult a dictionary. IMHO of course.
Title: Re: German in the code
Post by: isidoro on January 09, 2012, 01:58:11 AM
The difference between the get_weg line and the get_way line is that I understand the latter and not the former, and if I know programming I can try to guess what is done.  Otherwise, I have to look it up in a German dictionary, pray that it is not a typo or an obscure abbreviation, or a declination, or a verbal particle, or..., and try to guess.

And, then, the next line.  And when you translate some more, you forget the first ones.  It is a true pain.  And I can speak from my experience of a not nothern-family language speaker.  And the author of the first post is Spanish, as you can see.

Not to mention comments.  You have to be very, very lucky if you can make sense of what Google Translate spits in those cases.

English, we like it or not, is the de facto lingua franca in Computer Science.  As it used to be in other areas Latin first, French then, and who knows what next.

I may understand that this is not done because of the amount of work, complication, etc., but not done because it is not desired...
Title: Re: German in the code
Post by: missingpiece on January 09, 2012, 02:52:08 PM
The vocabulary of things should be relatively small in any given subject matter -- particularly verbs you do not need many.  Does it actually add that much, learning the name in addition to learning what an object and its methods do ? Also, would you not think that Germany proper names ( just as you learn any other name, like Isidoro ) set things of the program nicely apart from C language key words ?

I am eager to know that. Please explore your experience ! Non-English natives have probably just gotten so used to learning English that learning the name of a thing in a different language only feels different but maybe is not more work ? I am not coding much these days, but I am supervising non-English coders. I would really like to know how it is like.

An example of my experience : I started learning Arabic some time ago. And I found that learning the letters did not add much more complication ontop of nor slowed down particularly learning all the new words and grammar in the first place.
Title: Re: German in the code
Post by: Spike on January 09, 2012, 09:59:03 PM
If no one ever starts to translate the identifiers, the problem will stay forever. I think an intermediate worse state is acceptable if the goal is an improvement once reached.

I'd  also suggest a unification of identifiers, i.e. give variables which contain the same elements the same name. Above there was written that both "gr" and "bd" are frequently used for ground_t pointers, so one should be chosen an used (gr IMO, since that is closer to the English word ground).


I am eager to know that. Please explore your experience ! Non-English natives have probably just gotten so used to learning English that learning the name of a thing in a different language only feels different but maybe is not more work ? I am not coding much these days, but I am supervising non-English coders. I would really like to know how it is like.

I once tried to understand a program with Spanish comments and identifiers and it was _very_ difficult to figure out that is does, and how. Thus I suggest a move to English identifiers in Simutrans. If if means something, I never used German identifiers anymore in any of my other published projects, because I saw what troubles they caused to my non-german helpers in Simutrans. I consider it an interesting try, but since one never knows which project will be successful and which won't it's better to use English in _all_ projects.
Title: Re: German in the code
Post by: isidoro on January 09, 2012, 11:35:04 PM
@missingpiece: the answer from my personal experience is yes, no doubt.  You may not understand that since you know German and Portuguese, and supervising has nothing to do with understanding and easily follow and read code efficiently.

I can speak more or less English, Spanish.  I understand 90% French and even speak some, 99% written Italian and 99% written Portuguese (though I can't speak them).  I'm learning Chinese and I love those characters and can read some.  But German=Sanskrit to me, or Japanese, just the same.

And what happen if I'm in ten projects, one in German, two in Japanese, four in Greek, three in Russian?  I'd rather change my job and look for one in the United Nations, don't you think so?

In Computer Science and many other scientific activities, English is the key.  You like it or not.  And I don't mean I specially like it...  ;)


@Hajo: I like your new message "In search of slowness...".  Very nice.

Title: Re: German in the code
Post by: missingpiece on January 10, 2012, 10:00:26 AM
Thanks for the explanation. And, yes, I agree with English being ... the obvious and easy choice for international projects. German used to be the language of science, but these times are gone.

And on a side note : mixing grund and boden definitely confuses a German native coder, too.
Title: Re: German in the code
Post by: prissi on January 10, 2012, 10:06:41 AM
For me, most important is consistency. If get_plume() does not returns a plume(_t) or pointer to it, it is very confusing. In that regard einstellungen_t is a bad example: welt uses get_settings() to return einstellungen_t. That is imho harder to find out (without german) than get_einstellungen() return einstellungen_t. That you can understand without any german.

Thus if you want to change weg_t to way_t you have also tho change get_weg() to get_way() and strasse_t to street_t or else you will add more confusion. And doing this is a goo way to almost break any patch, thus this has to be done quite near a release with almost no pending big changes (like the routing system at the moment).
Title: Re: German in the code
Post by: missingpiece on January 10, 2012, 12:23:30 PM
this has to be done quite near a release

I hardly dare ask if there is a release schedule ? I mean in terms of an "ambitious target date", where some are working towards ? Maybe it is not a date but a set of must-have features which the community decided upon, where all maybe's go it which get ready in time.

If so....you could already announce that the release thereafter would be the translation release. And set the mind of each dev to then work on code-translation -- and only that. The head developer could make such an announcement without being hated for it.

The reward can potentially be three-fold :
  • the discussion now would stop and people focus
  • the sore development time for the translation release could hopefully be kept relatively short -- maybe four weeks
  • the newly achieved comprehensibility of the code may trigger more contribution (given theories in this thread are generally agreed to)
Title: Re: German in the code
Post by: morbidintel on January 10, 2012, 05:22:02 PM
I would like to join the dev team, though the foreign language does set a challenge.
But I believe attitude and enthusiasm is more important, cause I know I'll be willing to figure out the code.

The change doesn't have to be immediate, it could be subtle and done bit by bit(not literally!).
Though I'm new and still studying programming(for games), I'm still willing to help out however I can! (:
Title: Re: German in the code
Post by: Dwachs on January 10, 2012, 07:13:53 PM
I would be more than happy to commit any patches that translate something.
Title: Re: German in the code
Post by: prissi on January 10, 2012, 09:38:04 PM
If you change, do it right: Just avoid things like
strasse_t *str = get_way();

If it is not done this way, it won't be of use.

And it needs to be done AFTER a release, as such patches in the past always broke stuff. If one goes against engineers rule No 1 (Never touch a working system) then do so when it causes the least potential damage.
Title: Re: German in the code
Post by: TurfIt on January 10, 2012, 11:02:25 PM
If one goes against engineers rule No 1 (Never touch a working system) then do so when it causes the least potential damage.
Indeed. Especially when the cost/benefit ratio is so poor IMO.

Doing so around a release is of no help. I have tons of work in progress patches which would totally break after a mass translation, and which will be ready when ready; Not tied to any release. I can't imagine working up enough desire to go back and fix them all once broken by such a change.

But, if we're so hellbent on eliminating the German, do it once. One massive translation patch that kills it all. No point spreading this unnecessary pain out...

Title: Re: German in the code
Post by: missingpiece on January 11, 2012, 12:48:42 PM
The free floating patches in development, which TurfIt brings up, are one thing. What about James' experimental branch ?! How far off is it ? Will they be able to svn-merge the changes out of trunk ? But that will not catch lines where they use a (then renamed) variable in extended code portions in a function.

Should renaming possibly be an automated task ? Maybe something that the precompiler can be used for ( ouch, I'm talking about things I do not know more of than their name.... :-[ ) ?
Title: Re: German in the code
Post by: Spike on January 11, 2012, 09:49:55 PM
Indeed. Especially when the cost/benefit ratio is so poor IMO.

IMO having all code in English and with consistent identifiers will help further development quite a bit. From a software engineer's point of view it is a rather big benefit.
Title: Re: German in the code
Post by: jamespetts on January 11, 2012, 10:35:50 PM
In Experimental, I can run a search/replace to catch remaining items, although it would help me if (1) there were not too many things changed all in the same commit; and (2) the commit comments stated clearly exactly what had been changed to exactly what.

In the long term, if it makes it easier for people to contribute, Anglicising the code will be of benefit to Experimental, as it will encourage contributors. There are only so many hours in the day, and many of those I must spend working and sleeping!
Title: Re: German in the code
Post by: missingpiece on January 12, 2012, 12:28:19 PM
IMO having all code in English and with consistent identifiers will help further development quite a bit.
Is it an idea to consider that prissi -- or who ever feels being the "marketing" guy -- post a sticky announcement here in the forum, and potentially on the simutrans project page of sourceforge, that after the next release ( 112, I presume ) development work will focus on translating remaining German identifiers for release 113 ? That could probe the communities appreciation.
Title: Re: German in the code
Post by: prissi on January 12, 2012, 05:04:33 PM
Sorry, I am not the right person to address. I am very reluctantly changing something I worked 8 years to keep it working. Even when simutrans was closed source there were contributor. Therefore, *my* experience is that it is a lot of work with confuses all longer term contributor and causes new errors.

I once developed a nicely working patch for OptenTTD. During the development, the submitted cargo-packet (ok, could deal with that) and then changed to code to C++, including stuff in classes and so on. It broke the 3 month work in almost any line. Of course I did not worked on that any longer.

Such action, however well ment, could as well drive people away. It drove me away from OpenTTD contributions. But this is just MY personal opinion. If somebody does the work, ok. But I am not looking forward to integrate such a patch. It is for me work where you can only make new errors with not new features.

Even automatic refromatting the code in a consistent way is something I would like to do. In other projects I even spotted one or the other error by this. But I will not do it, as it will break any patch there (may also remove simutrans as base from experimental.)

That said, when I work on something and add new commetn or specifiers, I do all kind of reformatting, change to english and the like. But that place would have been broken anyways.
Title: Re: German in the code
Post by: Markohs on January 12, 2012, 05:46:05 PM
 Not being a german speaker myself, and finding german in code something that makes the development harder, I think the translation it's not really possible or worth, because of the reasons prissi already mencioned, mainly:

 - It whould make experimental and branch simutrans ever harder to keep in sync (well in fact it whould break all chances to keep it in sync)
 - I think it whould add lots of bugs and whould take lots of work.
 - Whould make all patches useless.
 - There is some documentation isidoro is working in that documents the code in depth, that's a great point to start reading and learning the code.

 I'd personally just:

 - Write in english NEW parts of the code, but variables and classes that already exist should remain as they are.
 - Keep isidoro's and rest of documentation up to date.
 - Translate all the code comments, there are a few still in german.
Title: Re: German in the code
Post by: VS on January 12, 2012, 06:00:01 PM
But... this isn't about changing the system, just names. How hard is it to do search & replace? After all, both of prissi's warning examples involved different code, not names.
Title: Re: German in the code
Post by: Ters on January 12, 2012, 06:39:56 PM
How can you search and replace in files on someone else's computer, that might be on the other side of the world and turned off at the moment? I have been a professional software developer for only a couple of years, but have seen many obviously harmless operations go very wrong.
Title: Re: German in the code
Post by: Spike on January 12, 2012, 09:23:13 PM
I guess it's the time to respect Prissi's voice as the current head developer. He says 'no' to the idea, and so we should spend our time on more worthy targets.
Title: Re: German in the code
Post by: jamespetts on January 12, 2012, 09:49:21 PM
Quote
- It whould make experimental and branch simutrans ever harder to keep in sync (well in fact it whould break all chances to keep it in sync)

While I shall refrain from commenting on the discussion more widely, I should note that this objection is somewhat misplaced. It is rare in any event that I am able to merge code from Standard without making manual changes to adapt it to Experimental. Translation patches have come in the past which I have been able to deal with relatively easily, where necessary by performing a search and replace in MSVC++. Do not, therefore, abandon this project on account of Experimental.
Title: Re: German in the code
Post by: Markohs on January 12, 2012, 10:02:34 PM
My guess was wrong then. Sorry. :)
Title: Re: German in the code
Post by: prissi on January 12, 2012, 10:11:10 PM
I do not object improving it at times. But why changing a section that has not been touched for years?

And I am not a boss, the above was my personal view as anybody else. I will work whatever the majority decides. I am certainly not the most active coder anymore, so I am in no position to deny such things.
Title: Re: German in the code
Post by: falconne on January 13, 2012, 03:09:40 AM
How about a wiki page with a glossary of common terms used and their translation? I currently keep Google Translate open on my second monitor; it would be easier to just have a page. Especially for German abbreviations that Google can't translate (I still haven't figured out what "besch" means) and variable names whose translation doesn't work worry well out of context.

I also think any kind of mass translation effort is not worth it and likely to break things, but it's definitely worth improving things bit by bit. Reading and understanding the code always takes a bit longer if you don't speak German, because the variables and methods don't register as well in your memory when you can't let your subconscious take care of it. Your brain's already trying hard to keep a lot of logic in immediate memory when you try to understand a complex piece of functionality, having to translate stuff in the middle of it breaks concentration and makes you forget bits.
Title: Re: German in the code
Post by: Dwachs on January 13, 2012, 07:53:09 AM
About 'besch': I guess it is short for 'Beschreibung', in English = 'Description / Descriptor'.

My 2 pfeng on this subject:

Imho, it hurts more to have incorrect or ancient comments in the code. Also filenames should reflect, what is inside. (Btw: did you know in which file the code for the display settings window was? The file was named colors.cc, I only renamed it some weeks ago).

What about the following policy for future coding work:
* any routine that is change in one commit should get Doxygen-like documented in a follow-up commit
* any routine with German name should be translated to English in a follow-up commit. For consistency, also routines with similar purpose should be translated, too.
Title: Re: German in the code
Post by: dom700 on January 13, 2012, 08:08:05 AM
As a native german speaker, I would like to point out that to me most of the comments / identifiers / classes are also sanskrit for me :) (or very good jokes, I love those comments)
If you would like to make it easier for people to work within the project, create a documentation file. Despite the (true) opinion that this project is well structured from karte onward, it's no good, if changing a hard coded variable takes an hour of looking for its location. It's especially problematic since this is typically the entry point for new people: changing a variable, changing a formula, whatever.
Title: Re: German in the code
Post by: prissi on January 13, 2012, 12:47:57 PM
Quote
* any routine with German name should be translated to English in a follow-up commit. For consistency, also routines with similar purpose should be translated, too.
That is a lot of work and will lead to great chaos. Or I have to change all get_besch() haus_besch_t to building_desc_t and so on at once. Otherwise for powerline it would return get_desc() to get building_desc_t and for smoke get_besch() and smoke_besch_t. (Not to mention that also a lot of file names needs changes then too.)

I will comment whenever I add something beyond trivial and I comment new routines. But I do not think the gradual transition work.

If one really wants to do some cleanup codewise: Lets say on June 1st (example) we submit a patch that:
- makes karte_t static, call it map_t (shorten than world_t) and replace all welt-> by map_t:: That would reduce a lot of hassle with obtaining a welt pointer at many places while still keeping the relation between things.
- Change einstellungen_t to game_settings_t and umgebung_t to user_settings_t.
- grund_t to ground_t and boden to soil_t? (and bd
- haus* ti house*
- fabrik* to factory*
- strasse_t to street_t and so on
- change all besch to desc.
- Do a automatic reformat to proper space seperation and indentation (currently different ways in the code)
- change comments to proper style, remove author line (mostly wrong anyways and reworked by many)

It would of course break almost any patch. But if given the warning ahead we may decide for a month for just either integrate a patch or remove it. Any patch must be incorporated before (or will need a lot of work to have it again). Any then we have a clean slate, patchwise but also from programm styles and so on. It will require experimental also a lot of work to get to the same state.

Personally, for me it is rather this or leave it as it is, and only change gradual comments and new identifier. Imho anything in between just will add to confusion and make suffering worse. Oldtimer like me will not find the old names, newcomer will be confused why a car has auto_besch_t and vice versa.
Title: Re: German in the code
Post by: jamespetts on January 13, 2012, 01:21:41 PM
May I suggest some alternative translations for some of the variable names?

besch > type
haus > building

Do we also not need to translate "planquadrat_t", or is that not German to start with (it does not make a great deal of sense in English if it is intended to be English)? And "ribi" has been discussed before as being unclear - perhaps "direction_mask" or "dir_bits"?

There is also, I think, stadt_t (town_t) and stadtauto_t (privatecar_t), as well as a word beginning with "v" whose spelling I forget for pedestrians (pedestrian_t), and further vehikel_t (vehicle_t). Connected are the methods that generate pedestrians and city cars whose German spellings I forget, but that I suggest be named "generate_privatecars" and "generate_pedestrians" respectively.

Also, there are the various "bauer" classes (tunnelbauer, and so forth) that could translate to, e.g., "tunnelbuilder_t". I think that bridges, too, are still "brucke" in the code.
Title: Re: German in the code
Post by: DirrrtyDirk on January 13, 2012, 02:04:01 PM
Do we also not need to translate "planquadrat_t", or is that not German to start with

It is german. You could translate it as (map) grid (square) or so. That language question being solved (hopefully), I'll leave you Dev guys alone again.  ;)
Title: Re: German in the code
Post by: jamespetts on January 13, 2012, 03:02:05 PM
gridsquare_t seems easy to understand.
Title: Re: German in the code
Post by: prissi on January 13, 2012, 03:51:45 PM
There is many more stuff. ANd of course we should discuss before what to choose.

But type is imho not a good translation for the description of an object, since type is already another fixed term in programming. "Overloading" that with a different meaning sound not like progress. The same would apply for definition. Although personally house_def_t sounds not too bad. (I would not use too long names, as during programming you have to type them too.)

If karte_t goes to map_t then planquadrat_t make rather sense as map_square_t to me.

But of course I am german. And the choosing of names should be neither british nor american, canadian but internationally compatible.
Title: Re: German in the code
Post by: isidoro on January 13, 2012, 04:07:52 PM
Imho, some translations are not worth the effort.  For instance, vehikel -> vehicle, karte_t -> map_t, hous -> house, fabrik -> factory, strasse -> street, since the German term resembles the English one and is not a problem when reading the code.  And it even looks cool and reminds the origin of the code.

However, besch -> desc, bauer -> builder, einstellungen, direction, etc. is much needed.

Title: Re: German in the code
Post by: TurfIt on January 13, 2012, 04:41:35 PM
Personally, for me it is rather this or leave it as it is, and only change gradual comments and new identifier. Imho anything in between just will add to confusion and make suffering worse.
Staying the course with the gradual changes is the only thing that makes sense. Maintains compatibility not only with the outstanding patches, but with the current contributors too. I truly don't see there being a lineup of people ready to jump into the code, but for all that German keeping them away...

I'm not German. My knowledge of the language doesn't exceed that which is overheard at Oktoberfest... In fact I'm currently quite uni-lingual having lost the minimal French from childhood. The presence of German in the code has not been a hindrance at all in getting to the level of familiarity I now have with the code.

planquadrat_t, gridsquare_t, or map_square_t, wouldn't have mattered when initially starting out with the code. Now, it demonstrates perfectly the problem. What is the correct word choice? I've already picked *my* choices and they're now seared into the mind forming a mental map of the code. If something different from what I've been using is chosen, extreme confusion. I don't think I could make that mental leap to update my map wholesale. Which really means relearning everything from scratch. Frankly, I don't think I have the desire to do so.


EDIT:
Just ran across a very applicable quote:
http://developers.slashdot.org/comments.pl?sid=2619084&cid=38684742 (http://developers.slashdot.org/comments.pl?sid=2619084&cid=38684742)
Quote
As for dealing with other people undocumented code, that's just a skill you need to have as an engineer, like being fluent in multiple languages many of which won't be your choice. You think I want this tool chain to be written in TCL? Should I then port it to my favourite language (e.g. perl) what if the next poerson to support it prefers python? It's just part of engineering that everyone else's code will look rubbish and undocumented to you. Even when it is documented you'll then think the documentation is overkill.
Undocumented or documented in a foreign language, close to the same thing. Suck it up and deal.
Title: Re: German in the code
Post by: sdog on January 13, 2012, 04:50:26 PM
being used to fortran, i'm a bit amused that the language of variables causes difficulties ;)

if a translation really is desired, couldn't perhaps instead of searching and replacing a very robust perl or python or awk script be used. This should also be applied to work in progress versions and patches, to address the issue TurfIt mentioned and conversion of experimental.



(i've difficulties reading c on the level used in simutrans, so please disregard my comment if it is not helpful)
Title: Re: German in the code
Post by: Combuijs on January 13, 2012, 07:06:53 PM
Quote
Undocumented or documented in a foreign language, close to the same thing. Suck it up and deal.

That is where I absolutely disagree. Undocumented code is far better understandable if the variable and type names are understandable (and chosen rightly...) . Otherwise you could just number your classes c1 to cn, number your variables v1 to vn and number your types t1 to tn. The code is then doing exactly the same, but it takes a lot of time to be understandable.

Documentation (or classes, variables, types) in a foreign language does not help if you don't know what they mean.

As for an example a C# code extract in Dutch (from my own software) stripped of commentary. I bet that a Dutchman will analyse the code twice as fast as an Englishman, just because he understands what the variables will do.

Code: [Select]
        private string NaamVolgensTaalRegel()
        {
            string NieuweNaam = "";
            char[] Separators = new char[2];
            Separators[0] = '[';
            Separators[1] = ']';
            string[] ParseStrings = mNaamTaalRegel.Split(Separators);
            bool ZeHoudtVanMe = true;
            for (int i = 0; i < ParseStrings.Length; i++)
            {
                string Part = ParseStrings[i];
                if (Part != "")
                {
                    if (ZeHoudtVanMe)
                    {
                        NieuweNaam = NieuweNaam + Part;
                    }
                    else
                    {
                        DhItem Item = ItemsIncompleet[Part];
                        if (Item != null)
                        {
                            object Waarde = Item.Waarde;
                            if (Waarde == null)
                            {
                                Waarde = Item.DefaultWaarde;
                            }
                            if (Waarde == null)
                            {
                                Waarde = Item.ForfaitaireWaarde;
                            }
                            if (Waarde != null)
                            {
                                NieuweNaam = NieuweNaam + DhWaarde.WaardeToString(Item.WaardeType, Waarde);
                            }
                        }
                    }
                }
                ZeHoudtVanMe = !ZeHoudtVanMe;
            }
            return NieuweNaam;
        }
Title: Re: German in the code
Post by: prissi on January 13, 2012, 07:48:17 PM
Stripping comments is never great, no matter what language. And I think that nobody disagreed about changing and adding comments.

Actually, the only very little was unclear in your example due to language:
ZeHoudtVanMe (should get a comment anyway) Google said this mean They love me ... with such a variable name I would not be so sure ;)
NaamVolgensTaalRegel (But such a "long" function should get a comment anyway)
That is all that might not be obvious by not speaking Dutch.

And without definition of DHItem  (anyway that is not really dutch, just letters ... ), object (what a name for a type!) and the type of mNaamTaalRegel one cannot guess really the meaning anyway, as with C++ and overloading of operators all strange stuff could happen.  ;)
Title: Re: German in the code
Post by: Spike on January 13, 2012, 09:46:49 PM
In the terminology of some Java teacher the besch* classes would go as "catalog like descriptions" for  objects which all share the same properties.

Well, not only Java: http://en.wikipedia.org/wiki/UML_colors

Quote
description — Is it simply a catalog-like description which classifies or 'labels' an object? If users of a system are labeled based on the department of a company they work within and this doesn't change the way the system behaves, this would be a description.

-> desc  ;)
Title: Re: German in the code
Post by: Combuijs on January 13, 2012, 10:08:41 PM
Quote
ZeHoudtVanMe (should get a comment anyway) Google said this mean They love me ... with such a variable name I would not be so sure (http://forum.simutrans.com/Smileys/default/wink.gif)

It actually means "She loves me"... (Note that the variable alternates between true and false: She loves me, she does not love me, she loves me, etc..., I wonder if they play that flower petal game outside the Netherlands too...  ;D ).

Quote
object (what a name for a type!)

That's actually the C# equivalent of C's void*.
Title: Re: German in the code
Post by: Isaac.Eiland-Hall on January 15, 2012, 01:25:04 PM
I truly don't see there being a lineup of people ready to jump into the code, but for all that German keeping them away...

EDIT: I'm one person, but probably very unimportant. (previously wrote way too much to say just that). And maybe I put too much important on not understanding terms when I tried. :)

She loves me, she does not love me,

Same game in English is phrased "She loves me. She loves me not." (etc.) - pulling petals off the flower, and the last petal represents the "true" answer, surely the same.

Title: Re: German in the code
Post by: Ashley on January 15, 2012, 02:02:47 PM
From my relatively little experience of the code base the German words are definitely the last thing I'd spend time refactoring out. I agree with Prissi about consistency being more important. Learning what umgebung and planquadrat mean is fairly easy in comparison with working out what's going on overall, and working that out is made miles easier through consistent documentation (in German or English - google translate is pretty good for German-English translation!) and consistent coding standards.

IMO ofc.
Title: Re: German in the code
Post by: isidoro on February 10, 2012, 12:07:42 AM
This is what I get from Google Translate for these two sentences in German:
Quote
Dies ist der x-Offset in Bilschirmkoordinaten bei der Darstellung des Objektbildes. Dies ist die Koordinate des Planquadrates in der Karte zu dem das Objekt gehört.

Quote
This is offset in the x-Bilschirmkoordinaten in the representation of the object image. This is the coordinate of the square in the map plan to which the object belongs.

What plan?  What Bilschir...?  Those sentences make no sense.

And those are not the worst cases I've found while visiting the code...  But you are right, if Google Translate works that nice from German to English, it will probably work the same from English to German, won't it?  Please, document in English at least...

I've been directly working with the code not farther than a month from now.  I've got no idea of what does umgebung means now.  A casual developer, and those are not to be neglected in an open source project due to lack of resources, may program by reading similar sections of the code he tries to implement and imitate them.  That's nearly impossible with code written in a foreign language.  I don't understand a word of Combujis' flower example.  If written in English, I would have understood it quickly and at once.

I am not a native English speaker.  I don't like the present state of things, but I don't understand why what is of application for the International Simutrans Forum, by a magic twist, is not applicable to the code of the program.  Let's speak German here, if all your argument is right.  Either that or rename the forum to the English Simutrans Forum...

P.S.: if I were a native English speaker, I wouldn't probably like things as they are.  English is by far the worst treated languages of all by non-native speakers like me.  I wouldn't like that to be done to my language either...  But they worked hard to achieve it...

Title: Re: German in the code
Post by: sdog on February 10, 2012, 12:27:43 AM

here are some translations for you:

the first is just a typo: Bildschirm means screen


planquadrat is not well translated by google, it is a square of a map grid


umgebung is the set of points with a distance smaller than a set limit.
most likely you know an epsilon-umgebung form school (the german word is often used in english textbooks afaik)




p.s.: (off topic)
"English is by far the worst treated languages of all by non-native speakers like me."
i'd not be so sure, my experience with marking undergraduate's texts in canada is that non-native speakers are much more likely to deliver something readable than native speakers. the errors in grammar are also typically less severe than those of native speakers, spelling is very rarely wrong with non-native speakers.
I should rather say, native speakers work hard enough themselves to mistreat their language.
Title: Re: German in the code
Post by: isidoro on February 10, 2012, 01:01:48 AM
[...]
"English is by far the worst treated languages of all by non-native speakers like me."
i'd not be so sure, my experience with marking undergraduate's texts in canada
[...]

Touché!  :)
Title: Re: German in the code
Post by: IgorEliezer on February 10, 2012, 03:43:32 AM
I could say:
  • It seems there's a consensus that, a code in English would make the Simutrans source code more inviting for new coders. (It's already attracting new people)
  • It seems there's a consensus that, a translation is or will be necessary.
  • But, there's no consensus the code should be fully translated now. Some developers might or could "lose the track" if it happens.
  • Nonetheless, some few people think that something should be done, from now on.
Then, my conclusion:
The translation is necessary, we agree with it; but we haven't decided about "when and how" to do that. I would propose the developers could choose what parts or elements of the code could be translated. People translate these parts and summit. Once incorporated into the code, the developers choose other elements of the code, and so on, until full completion.
Title: Re: German in the code
Post by: sdog on February 10, 2012, 05:27:27 AM
i don't think there is anyone in this thread against translating comments, what isidoro posted was obviously a comment. this a little different from translating the source code and is better kept distinct in the discussion.

(got only involved in the thread as i thought isidoro needed translations, as i'm no coder, i have and want no say.)
Title: Re: German in the code
Post by: Dwachs on February 10, 2012, 08:25:13 AM
umgebung is the set of points with a distance smaller than a set limit.
most likely you know an epsilon-umgebung form school (the german word is often used in english textbooks afaik)
rofl Let epsilon be so small such that epsilon/2 is already negative ^^

umgebung_t should be translated to environment: all settings that can be changed without an effect on the simulation, ie these settings only change the look & feel of the program but not the behavior of the game simulation.

My 2 cents on this topic: Why not develop a script that does the translation? Then patches and forks of simutrans-standard can be translated much easier. Merging changes where every line changed is not fun. And I would suggest to do it piece by piece: the besch system, the gui, ding_t 's etc.
Title: Re: German in the code
Post by: Spike on February 10, 2012, 09:28:37 AM
I have started to translate identifiers in my "Simutrans Iron Bite" branch. It's been part of what I considered to be important:

http://forum.simutrans.com/index.php?board=99.0 (http://forum.simutrans.com/index.php?board=99.0)

I started with some type and method names. But it will take time to translate everything. At the moment I have no scripts for this yet, though, I do it manually.
Title: Re: German in the code
Post by: Dwachs on February 10, 2012, 09:37:23 AM
I have started to translate identifiers in my "Simutrans Iron Bite" branch. It's been part of what I considered to be important:
Which is a bad idea imho, as it makes it unnecessarily difficult to produce patches to transfer work on new features into simutrans-standard.
Title: Re: German in the code
Post by: Spike on February 10, 2012, 09:44:34 AM
I guess I make myselve unloved this way, but it is intentional that my changes are hard to merge back. You have refused to let me work with you on Standard, I got no direct access to change the code, and I was told my changes are unwished/unliked.

So I do my own thing with my ideas and if you should change your mind and consider my changes good some day, I want that you have it really hard to get them back into Standard.
Title: Re: German in the code
Post by: omikron on February 10, 2012, 10:13:07 AM
Welcome to the kindergarden....

Do you think you achieve anything this way, Memzeron?
Title: Re: German in the code
Post by: Spike on February 10, 2012, 10:45:40 AM
Yes.

1) I achieve control over my development line. I'm tired of all this arguing if my ideas are good and bad. On my branch I can just go and do it.

2) I don't like how I was/am excluded from main development. I shall make patches and wait days for them to be include? Never. If they exclude me, I exclude them. I had tried to get into the team, but wasn't allowed. Why should I support people who have declared not to want my changes in the first place?

3) I think I am a competent coder (No, that doesn't mean best programmer of the world. Just someone who knows what he does, and who has many years of experience in the field). I will try to outperform Prissi and Dwachs by providing a better code base, and attract patch makers and developers to my code base, because they can read it better and develop quicker with my code. At the moment my code compiles quicker, that saves each developer some minutes for each full build already. And I achieved that in only a few days.

*shrugs*

But hey, why should I care at all? Dwachs and Prissi don't like me and my ideas either, and the discussion about that took way too long. So I'll do my own thing from now. It's unimportant to me what they think or do, if they have it easy or not - I believe that I have good reasons for my decisions (about what is good in coding, and about good UI design), and I'll do what I consider the right thing to do. Why should I bother with people who have different ideas, and think they are right with their ideas? We'll never get together anyways.

See how long it took to discuss if german is bad in the code? Now that I've started my branch, and translated some identiefiers, suddenly Dwachs wants to translate, too. Before that eveyone was against translating the code becase of reasons bla and blubb. Heh. I know it's good to have English code since most developers can read it. So I don't need to discuss that with anybody, I just need to do the translation.

kthnxbye.
Title: Re: German in the code
Post by: jamespetts on February 10, 2012, 10:53:24 AM
Of course, if the Standard developers wanted to translate the code, and be able to use parts from Iron Byte, they could just adopt Hajo's translations ;-)
Title: Re: German in the code
Post by: Spike on February 10, 2012, 11:06:03 AM
At the moment my code compiles quicker, that saves each developer some minutes for each full build already.

Before Dwachs calls me a liar again (and last time I could prove that I told the truth), I want to be more precise: Compile times came down with make/gcc, what I'm using. It is well possible that MSVC is different, and I can't check that. So I can only say "compiles faster with gcc".
Title: Re: German in the code
Post by: Spike on February 10, 2012, 11:07:50 AM
Of course, if the Standard developers wanted to translate the code, and be able to use parts from Iron Byte, they could just adopt Hajo's translations ;)

I've tried to intermingle translations and othe code changes, so the usual SVN diff tools will not allow them to get clean patches from my commits. Being a developer since many years I know pretty well what makes the life of a developer difficult. They would have to take all, and I know that Prissi doesn't want my UI layout changes, and they won't get the translations without the layout changes. I'm pissed and I told them that I'll not play nice anymore after they have offended me. But I'll now wait a while and see what they do, and then reconsider my plans.

Edit:

Bleh. What sort of discussion is this? Dwachs isn't online anymore, that Omikron guy logged off after throwing that message at me, and Prissi is nowhere to be seen. Now I can again wait for hours to get a reply of the important people. I hate that sort of waiting in uncertainty. It kills me.
Title: Re: German in the code
Post by: Dwachs on February 10, 2012, 11:38:36 AM
Why pushing others to answer your posts? There is no need to add anything here. Thank you for your clear words that revealed you intentions.

Quote
I shall make patches and wait days for them to be include?
I still have to see your second patch. The first one was included 20 minutes after you published it.
Title: Re: German in the code
Post by: Ashley on February 10, 2012, 11:47:48 AM
I am locking this topic, it serves no productive purpose.


Please, everyone, sort out these private issues in private. There is no need to rip the community apart over this.


Edit: It seems that this discussion may be useful afterall. Please continue.
Title: Re: German in the code
Post by: whoami on May 30, 2012, 06:01:45 PM
I have written a Perl script to run an automatic translation of the C/C++ source code identifiers, using a simple list file for old->new identifiers. This works quite well for the actual source, checking for any conflicts beforehand, which is possible because the whole relevant code is accessible. With some changes to the translation table, it would be usable by the forked projects, too. I have not looked at Hajo's translations, but they could be integrated as well.

The problem is not so much with the code, but with the comments:

They are not treated specially yet, but I intend to change this. The current state leads to the ugly effect that single words in German comments are translated (rather than feeding whole paragraphs to some Babelfish successor  8) ). However, I cannot simply omit stuff in comments, because they often refer to identifiers, some even contain commented-out code lines, and they are used by diff. This will not be solvable in an optimal way. (If there are nested /**/ comments, they make handling even more difficult - I would rather remove nesting by separate patches.)

I already try to support .diff files, but their context part does not tell reliably what line is a comment, so they depend on translated comments, thus the easiest way would be to translate comments in all cases, but disregard them for conflict checks. Otherwise, I would have to emulate patch as well and compare to the original file, which I probably will not try at all.

Of course, my translation list is far from complete. Currently, 31,571 string replacements will be suggested (including comments). The current impediment is the set of false identifier conflicts caused by comments and, to a smaller extent, code already using English identifiers that are the same as natural translations of the German ones.

Not to forget: I have not seen a missing text translation (caused by my changes) in the game yet, but if that became a problem, separate handling of strings would be mandated.

(edited to improve transfer of information to the reader)
Title: Re: German in the code
Post by: Combuijs on May 30, 2012, 06:07:20 PM
Hmm, interesting!
Title: Re: German in the code
Post by: sdog on May 30, 2012, 06:17:03 PM
The problem not so much with the code, but with the comments:

They are not treated specially yet, but I intend to change this. The current state leads to the ugly effect that single words in German comments are translated (rather than feeding whole paragraphs to some Babelfish successor  8) ). However, I cannot simply omit stuff in comments, because they often refer to identifiers, some even contain commented-out code lines, and they are used by diff. This will not be solvable in an optimal way. (If there are nested /**/ comments, they make handling even more difficult - I would rather remove nesting by separate patches.)
You could add a line below comments where you put the translated and untranslated strings in a fixed format. The comments likely have to be translated by hand and patched by their own. This note will give translators a way to know that variables have changed in the meantime.


"[...] code already using English identifiers that are the same as natural translations of the German ones."
I'm afraid, I dont' understand this.
Title: Re: German in the code
Post by: whoami on May 30, 2012, 07:02:46 PM
You could add a line below comments where you put the translated and untranslated strings in a fixed format. The comments likely have to be translated by hand and patched by their own. This note will give translators a way to know that variables have changed in the meantime.
It will be possible to recognize whole comment blocks and handle them as an entity, but not a random mixture of commented-out code and short remarks.

Quote
"[...] code already using English identifiers that are the same as natural translations of the German ones."
I'm afraid, I dont' understand this.
Example: "weg" is used, but also "way", same for bild/picture, get_typ/get_type, groesse/size and many more. The laziest^Weasiest solution would be to add a suffix to the translated ones.

The number of replacements that I mentioned is without touching "ribi" (direction bits) and "sp" (player), by the way.
Title: Re: German in the code
Post by: eipi on May 30, 2012, 07:04:53 PM
I already started to translate the code comments into English since a while ago I ran Doxygen on the source code and realized the comments lacked a bit of consistency :)

The patch is not complete yet, but I am still working on it when I have time.
http://dl.dropbox.com/u/53679800/Simutrans/patches/SimuTranslation_bauer.patch
Title: Re: German in the code
Post by: prissi on May 30, 2012, 07:06:58 PM
This looks like simple text search an replace. Such a script would need to parse at least comments/strings/defines. Or some unhappy surprises will come up.

As important as such a tool would be consent on how to actually rename stuff. Because this procedure should not repeated too many times ...

Adding a suffix will not change anything but rather cause more confusion. get_way or get_way_en for instance ?!?
Title: Re: German in the code
Post by: whoami on May 30, 2012, 07:09:04 PM
@Eipi: since you work on the comments, your changes and mine are the ideal complement to each other, yours to be applied first. Do you keep this in sync with the ongoing development?
Title: Re: German in the code
Post by: Dwachs on May 30, 2012, 07:10:05 PM
I would not care that much about German comments. As they are certainly some years old. If the automatic translation 'only' creates a mixture of German / English words in a comment then this is tolerable, imho.

@eipi: I think it would be enough to first start to translate and comment the functions etc in Doxygen style.
Title: Re: German in the code
Post by: whoami on May 30, 2012, 07:14:11 PM
@Prissi: My script is only built around
Code: [Select]
s/\b$o\b/$trl{$o}/g (replace exact word match, but handle e.g. #include differently), but as I check for conflicts between all sets of strings involved, no conflict should arise. The conflicts check is global and therefore complains if there is no real conflict because the identifiers would be in nonoverlapping scopes. So there are false alerts and unnecessary work, but no conflict is supposed to show in the result.
EDIT: another way: first rename the few conflicting identifiers.

Adding a suffix will not change anything but rather cause more confusion. get_way or get_way_en for instance ?!?
Something like that, yes, or use a different word (less preferable).
Title: Re: German in the code
Post by: Dwachs on May 30, 2012, 07:23:41 PM
checking for any conflicts beforehand, which is possible because the whole relevant code is accessible.
What do you mean by conflicts here ?

And why is use of 'weg' and 'way' difficult to handle ? You do not need to translate way after all, it should not be matched by the translation table. Adding suffixes sounds like a bad idea to solve this.
Title: Re: German in the code
Post by: whoami on May 30, 2012, 07:30:08 PM
Well, I do not even pretend that I parse C++, and therefore I have no information what is a constant, class, variable, member function, enum item etc. I only have a bidirectional mapping of names, so I have to change all occurrences of one old name in all files to the new name, which must not exist before this change. Thereby, syntax and semantics of the code stay the same. In other languages, you can do funny things with eval, creating code on the fly, and I guess that it is possible to access and manipulate the symbol tables in C/C++ too, but ST does not try that, right?
Title: Re: German in the code
Post by: VS on May 30, 2012, 07:54:05 PM
Umm, the way I understand that is that you should be able to tell if a match is an identifier, or part of a comment or string.
Title: Re: German in the code
Post by: whoami on May 30, 2012, 08:07:41 PM
It is easily possible (though not implemented yet) to handle comments and strings in a different way, but there still are some identifiers with the same name as the best (natural) translation for some German identifiers, and those can be real, harmful conflicts. Without the complete conflicts check, I had a changed version that compiled completely, but crashed on starting, due to variables popping up with the same name as the ones that are actually meant.
Title: Re: German in the code
Post by: Ters on May 30, 2012, 08:10:00 PM
If German is difficult to understand, then German translated to English by a computer program will be beyond any hope of understanding. Especially with the abbreviations and special terms used in the code.

And as written above, some of the comments are outdated. I noticed a day or two ago that the one for way_obj_besch_t wasn't correct.
Title: Re: German in the code
Post by: whoami on May 30, 2012, 08:21:57 PM
My plan is to translate only identifiers, and all of them at the same time in a consistent manner (although it is possible the split it into phases, e.g. one for each area or class). I will have to see how far I get with comment handling.
Title: Re: German in the code
Post by: jk271 on May 30, 2012, 08:36:22 PM
I suggest to translate "spieler_t" to "company_t", not "player_t". I have read here in forum some time ago about intention to enable more players (persons) to control one transport company.
Today players can do it too, but they have to share password.

Such a translation change would avoid confusion in future: Implementation of unique password for each players would probably need keyword "player" as a class name.
Title: Re: German in the code
Post by: Ashley on May 30, 2012, 09:02:06 PM
I suggest to translate "spieler_t" to "company_t", not "player_t". I have read here in forum some time ago about intention to enable more players (persons) to control one transport company.
Today players can do it too, but they have to share password.

Such a translation change would avoid confusion in future: Implementation of unique password for each players would probably need keyword "player" as a class name.

Agreed, we need to be clear on this distinction in future.
Title: Re: German in the code
Post by: prissi on May 30, 2012, 09:14:35 PM
We had also clients in the game ... but player company seems a better description.
Title: Re: German in the code
Post by: whoami on June 04, 2012, 11:21:56 PM
Small update regarding my script (I did not have much time to work on it):
I am now able to handle comments and strings to some extent, so strings can be excluded from translation, although it would be most useful to also translate all the debug messages and XML tags (but that needs some code change to allow both the old and the new class names to be supported in settings.xml and XML savegames). Also, I would rather convert the GUI output strings and the translation files (and reimport them into Simutranslator) instead of still keeping German in them. (And I am able to fix spelling errors, too. :) )

I introduced a separate preparation phase, where I first change some existing English names (~4000 replacements, usually adding "_" to the name) to make room for the real stuff (~50,000 changes from a mapping table with ~800 entries, still increasing).

It seems that translating all the comments will be the best way, because not many are changed at all, and the changes concern mostly identifiers. Oh, and the filenames and folder names could be translated automatically, too (of course changing the #include lines).

I attach the changed simworld.h as a small example (even this is not completely done).
EDIT: I just noticed an error in this file, but this alone will not compile anyway.
Title: Re: German in the code
Post by: sdog on June 04, 2012, 11:52:49 PM
Quote
Oh, and the filenames and folder names could be translated automatically, too (of course changing the #include lines).

How would SVN cope with that, and are the german names of files also obstacles to understanding the program, enough to warrant the reduction in continuity?
Title: Re: German in the code
Post by: whoami on June 04, 2012, 11:56:34 PM
My SVN client has a rename function, but it might only be there to ease the process of "delete under old name, create under new name". Also, I often get SVN hickups here when I use that function.
Title: Re: German in the code
Post by: Ters on June 05, 2012, 04:59:12 AM
Last I checked, SVN's rename functionality is essentially based on deleting the file, and creating a new file as a fork of the deleted file. That's a way of doing it that is not unique to SVN. I haven't tried it with SVN, but merging changes to a moved file from a branch that hasn't moved might not work automatically.
Title: Re: German in the code
Post by: Dwachs on June 05, 2012, 06:41:27 AM
Imho, first the translation part should be sorted out. Moving & Renaming files is a rather trivial part compared to this.
Title: Re: German in the code
Post by: VS on June 05, 2012, 09:05:45 AM
Technical note: The "renamed" files can have a property telling where they came from. I know that Tortoise can use this information when browsing logs, no idea about other situations... Anyway, it would be good not to miss this :)
Title: Re: German in the code
Post by: whoami on June 05, 2012, 02:57:11 PM
Moving & Renaming files is a rather trivial part compared to this.
But I think that this needs to be automated, too, if one wants to keep .diff files in a working state. (I do not know how many patches are maintained separately from the trunk.) And let's not forget about ST-Experimental, ST-3D and Iron Bite (I didn't talk to anyone except from this thread).
Title: Re: German in the code
Post by: Markohs on June 05, 2012, 03:02:12 PM
st-3d won't be much of a problem I guess, just merging the repository with trunk should work, I've doine it various times already and it kept track of added/deleted files, and all the changes were fairly easy to merge, with almost no manual work.
Title: Re: German in the code
Post by: isidoro on June 05, 2012, 10:18:11 PM
@whoami:  your work is wonderful!  The file, to my eyes, is much more clear.  I don't know if changing the name of the files is worth the effort, though.  You are always one click away of looking inside...  The comments would be much better (better still if an expert in the code can update them and give them uniformity or a standard format)

Title: Re: German in the code
Post by: Dwachs on June 06, 2012, 06:09:41 AM
@isidoro: The translated header file looks as messy as the untranslated one :P But simworld.h is really bloated with functionality, which could be splitted into smaller chunks (management of global lists, all the event-related stuff, the main game loop, all these terraforming and world-generation functions ...)

That said, I am looking forward to use the translation script ... and debug the outcome :)
Quote
better still if an expert in the code can update them and give them uniformity or a standard format
I took me two evenings to do this for dataobj/umgebung.h, up-to-date comments would be nice but are time-consuming to generate... Better do this on the fly.
Title: Re: German in the code
Post by: whoami on June 06, 2012, 05:28:38 PM
I guess it would be useful to share the current state of the little tool and the tables, no matter how messy and incomplete the whole thing still is (the translation table started as a quick setup to be able to evaluate the whole approach, therefore needs to be restructured). WARNING: RUN THIS ONLY ON A COPY OF THE FILES! They are expected in .\trunk-copy (I advise to use "clean"ed source code, the IDE, if any, must not keep the files open). The script needs Perl >=5.8, for Windows e.g. the free "Community Edition" from ActiveState: http://www.activestate.com/activeperl (http://www.activestate.com/activeperl) -

The file tr.cmd is a frontend to save typing on Windows, the actual file translate.pl should run on any platform (EDIT: but the file names will be shown with \'s). You might need to adapt the paths in it and then call:
tr phase1 check
tr phase1 sim
tr phase1 translate
tr phase2 check
tr phase2 sim
tr phase2 translate
The sim and check calls are optional and do not change the files. But if "check" shows warnings, sim/translate will fail. EDIT: A lot of output is printed on the screen - you better minimize the cmd.exe window or switch off debug output in order to achieve acceptable performance. If additional translations have been entered in the text tables, a delta update can be run with the same commands, but a check is not possible after translation, and phase 1 must not run after phase 2 changes have happened.

I do not have access to a (commercial) refactoring tool, which could do the whole job or at least help a lot. For parsing C++ (in Perl), I did not find much (as opposed to plain C), but if I use GCC's dump function, it would still be much easier (and probably faster at runtime) than writing a C++ parser and dependency tracker on my own.
But this kind of understanding of the code would only save the unnecessary phase1 changes (due to false conflicts) and allow for better texts in some cases.

EDIT: the current version translates single words in comments, but not in strings of any kind.
Title: Re: German in the code
Post by: Dwachs on June 06, 2012, 07:15:25 PM
What is the point in renaming get_count to get_count_ first?

You should also adjust the usage-comment, the command is check not checkall.

Now I do not know how to proceed. Translating all the code at once seems to be not sensible. I do not want to end up with names with trailing underscores.
Title: Re: German in the code
Post by: eipi on June 06, 2012, 07:55:42 PM
@Eipi: since you work on the comments, your changes and mine are the ideal complement to each other, yours to be applied first. Do you keep this in sync with the ongoing development?

Yes, I try to, if I have time. My plan was  to get finished with the translation until the end of the year, maybe a bit sooner. However, progress is slow as I am no expert with the code and if anybody spots an error, feel free to notify me of them. :)
Title: Re: German in the code
Post by: whoami on June 06, 2012, 07:58:10 PM
What is the point in renaming get_count to get_count_ first?
Both get_count and get_anzahl exist in the original files, same with many others (as said). I assume that the English ones of these pairs were introduced later and are therefore used in a narrower context and in lower numbers. I plan to look up all the conflicting English ones (file for phase1, perhaps 100 names in the end) and find more specific names for their context and use, but currently, I just move them out of the way with the appended "_".

Quote
You should also adjust the usage-comment, the command is check not checkall.
The usage comment had more outdated information, I have changed it.

Quote
Now I do not know how to proceed.
Have you run phase2?

Quote
Translating all the code at once seems to be not sensible.
Phase2 can be split by splitting the translation table, e.g. between classes or files.

Quote
I do not want to end up with names with trailing underscores.
(Some of these exist already in the code.) The problem is: if I ignore and allow the potential conflict from naming two things the same, I cannot guarantee that there are no actual, undesirable name clashes, leading to overridden variables or class members. I hope that I get rid of the trailing _ in phase1, instead of writing a single-use code monster (parser and some semantics) which might take months to complete (and then be rejected for actual use because it's not understandable by anyone, including me).

I looked for professional tools: MSVS 2010 seems to be available only as time-limited trial (nowadays), not as express edition, and tools like Visual Assist (which should do C++ refactoring) do not support the latter anyway. So I will stick with VS 2008.
Title: Re: German in the code
Post by: Markohs on June 07, 2012, 09:54:09 AM
I looked for professional tools: MSVS 2010 seems to be available only as time-limited trial (nowadays), not as express edition, and tools like Visual Assist (which should do C++ refactoring) do not support the latter anyway. So I will stick with VS 2008.

 http://www.microsoft.com/visualstudio/en-us/products/2010-editions/express (http://www.microsoft.com/visualstudio/en-us/products/2010-editions/express) here, down the page, you can download the visual studio 2010 suites, (for example the C++ http://www.microsoft.com/visualstudio/en-us/products/2010-editions/visual-cpp-express (http://www.microsoft.com/visualstudio/en-us/products/2010-editions/visual-cpp-express)) . They are free, complete compilers, hurry up before they delete the 2010 version forever, since looks like they want all to migrate to 2012. :)
Title: Re: German in the code
Post by: Vonjo on June 07, 2012, 01:22:16 PM
Sadly, there will be no Visual C++ 2012 Express. :(
Title: Re: German in the code
Post by: whoami on June 07, 2012, 06:01:24 PM
OK, so M$ did not remove the download from all sites, but I can only see a web installer. Once they decide to not distribute it any more, I cannot reinstall it. But it's "free" as in "we lend it to you with no rent".

I installed VS2010 Pro Trial in a VM to use VA (or something else) with it, but I guess that the trial/evaluation license would not allow me to distribute the results to the public.

(BTW, I remembered too late that I use Unix tools on Windows in tr.cmd - just replace those calls, e.g. "tee" by ">>" redirection.)

Could this be moved to a developer board to (perhaps) get more feedback? I would like to know whether I should continue with the current approach.
Title: Re: German in the code
Post by: Markohs on June 07, 2012, 06:27:09 PM
there is also iso images on the link I posted iirc
Title: Re: German in the code
Post by: jamespetts on June 07, 2012, 08:10:57 PM
According to Microsoft (http://www.microsoft.com/visualstudio/11/en-us/products/express), Visual Studio 2010 Express will remain available for download even after the release of Visual Studio 2012.
Title: Re: German in the code
Post by: Fabio on June 07, 2012, 08:38:33 PM
Is larger projects a suitable board?
Title: Re: German in the code
Post by: whoami on June 07, 2012, 08:58:07 PM
The root development board will fit best, I think.

I would call this a technical conversion and not a large project, although the resulting .diff could have twice the size of the entire source code. :)
Title: Re: German in the code
Post by: Fabio on June 07, 2012, 10:24:03 PM
Actually, there's no development board. There's patches board, but there it would be drowned among scores of threads. Larger projects was created to single complex projects which development can last long time.
Title: Re: German in the code
Post by: whoami on June 08, 2012, 11:29:34 AM
I won't mind if it goes into "Patches & Projects", but "Larger Projects" may be a better choice, as this is not going to happen fast in any case: even if the method is accepted, there is still much to be discussed what to translate how.
Title: Re: German in the code
Post by: Fabio on June 08, 2012, 01:49:13 PM
Moved!
Title: Re: German in the code
Post by: eipi on June 13, 2012, 10:42:07 PM
@Fabio: Thanks for moving! In my opinion this thread fits best in "Larger projects" now.

My comment translation is progressing. What has been done up until now:

  • Doxygen comments for nearly all previously documented methods except for most of the GUI code. I might have overlooked some, though.  :)
  • A few comments have been translated, too.
  • The files in ./bauer are finished totally, I guess.
  • I added a doxyfile in ./documentation which generates only HTML output.

the patch file against r5773 is here:
https://dl.dropbox.com/u/53679800/Simutrans/patches/SimuTranslation.patch (https://dl.dropbox.com/u/53679800/Simutrans/patches/SimuTranslation.patch)

(Already > 22k lines and haven't really started yet :o )
Title: Re: German in the code
Post by: Dwachs on June 14, 2012, 06:26:38 AM
Impressive and most usefull! Will check this later.

Did you find any methods etc that could be deleted or moved to a different class (to provide cleaner interfaces) ?

I have also a patch to document some unimportant files (powernet and zeiger).
Title: Re: German in the code
Post by: Markohs on June 14, 2012, 07:49:36 AM
Good work!

 Just having it a quick look, I think I spotted some errors:

* you are removing the documentation in *fabrikbauer_t::get_random_consumer
* triple empty line separating fabrikbauer_t::alles_geladen and  fabrikbauer_t::finde_anzahl_hersteller (line 247, should be just 2 empty lines, this happens everywere)
* removing doc at *fabrikbauer_t::finde_hersteller
Title: Re: German in the code
Post by: eipi on June 14, 2012, 06:57:08 PM
triple empty line separating fabrikbauer_t::alles_geladen and  fabrikbauer_t::finde_anzahl_hersteller (line 247, should be just 2 empty lines, this happens everywere)

Ah ok, didn't know that there should be only 2 lines between methods. Fixed now.

I saw that some methods (like fabrikbauer_t::get_random_consumer()) had comments in both header and source files so I moved them to the header file to keep it all in one place. There might be some lines that haven't made it so I'll check that again.

Did you find any methods etc that could be deleted or moved to a different class (to provide cleaner interfaces) ?

I haven't had time to dig into that, I am just trying to get an overview of the code while doing the documentation so this has to wait a bit.
Title: Re: German in the code
Post by: Dwachs on June 14, 2012, 07:11:11 PM
According to Doxygen manual @return and @returns are both available, so there is no point in chaning one to the other type.

I will check and commit your stuff piece by piece if the next release is out :)
Title: Re: German in the code
Post by: prissi on June 15, 2012, 08:38:45 PM
Stupid question: Is there a simple tool to keep both comment in header and in cc in sync? The reason is that many private or seldom called functions functions are rather better documented there since they are only called from teh same module

Also only comments in a function but not clue on top what it does is also strange. (Personally, I would rather prefer the implementation with the documentation, but aparently the community voted otherwise.)
Title: Re: German in the code
Post by: Dwachs on June 16, 2012, 08:56:58 AM
Iirc it is perfectly possible to have the documentation near the implementation, I think doxygen can still generate correct documentation out of it.

We need to agree on one particular style.
Title: Re: German in the code
Post by: Ters on June 16, 2012, 09:45:28 AM
When I have used Doxygen, which isn't often, I have put the documentation near the implementation. There are two reasons for this:
  • When you change the implementation and need to update the documentation, the documentation is right there.
  • I like to keep the header files minimal so that I can easily glance over them. Smaller header files are also probably faster to include in other files.
Title: Re: German in the code
Post by: Markohs on June 16, 2012, 04:55:07 PM
Documenting just the includes has one advantage, I think, so the IDE can show the function documentation when you hover over it, as you are typing the code. I'd prefer personally document the headers, but as you already said, we just need to agree in a single way of doing it and just do it, on code or on includes, but just a single decision.
Title: Re: German in the code
Post by: Ters on June 16, 2012, 10:46:39 PM
As long as the source files are avaiable, the IDE should in theory be able to show the documentation either way. For libraries, especially closed source ones, documenting the headers would be the only solution, but that's not the case here.
Title: Re: German in the code
Post by: prissi on June 17, 2012, 09:15:00 PM
Unfourtunately I did not found out how to do this in MSVC.

And it really depends: For trivial functions, documenation of the header is certainly ok. But for more complex function, this is not enough imho. And then things get tricky with virtual functions. In principle only the "original" should be then documented.
Title: Re: German in the code
Post by: Markohs on June 18, 2012, 09:48:14 AM
for msvc to pick the comments in the includes, the syntax is sightly different, but it's compatible with doxygen I think:
Code: [Select]
    /*!    \brief        Convenience function that creates the required objects to initialise the        CEGUI system.        The created Renderer will use the current OpenGL viewport as it's        default surface size.        This will create and initialise the following objects for you:        - CEGUI::OpenGLRenderer        - CEGUI::DefaultResourceProvider        - CEGUI::System    \param display_size        Size object describing the initial display resolution.    \param tt_type        Specifies one of the TextureTargetType enumerated values indicating the        desired TextureTarget type to be used.  Defaults to TTT_AUTO.    \return        Reference to the CEGUI::OpenGLRenderer object that was created.    */    static OpenGLRenderer& bootstrapSystem(const Size& display_size,                                  const TextureTargetType tt_type = TTT_AUTO); EDIT: According to this (http://www.stack.nl/%7Edimitri/doxygen/docblocks.html), that's the QT-style, msvc 2010 at least, sopports that style I think. EDIT2: Microsoft points us to XML documentation for this, but in my oppinion it's too verbose, and I'd stick with doxygen instead. Link (http://stackoverflow.com/questions/3864201/using-doxygen-with-visual-studio-2010).

EDIT3: mmm... All the information I posted i'ts not true, looks like you either use XML documentation in MSVC, or you document doxygen style, and use it to generate a .xml for Intellisense, having it a look.
Title: Re: German in the code
Post by: Markohs on June 18, 2012, 11:53:19 AM
After spending some hours trying to get intelisense to work, I've failed, the only way of making it work is using XML style documentation, that uses something similar to:

Code: [Select]
/// <summary>
/// This functions documentation
/// </summary>
/// <param name="aa">blablabla</param>
/// <returns></returns>
bool function1(TypeX aa);

 Looks like this style it's also accepted by Doxygen, and it's automatically processed and shown by Visual Studio Intellisense.

 I see it one advantage over:
Code: [Select]
/*!
 * blablabla
 * \param
 */

 And that's that you can comment entire sections of code, because you won't have a '*/' in the middle of the code.

 Anyway I don't personally like it, I'd suggest:

 * Use doxygen as the generator of the documentation
 * Make header (.h) documentation mandatory
 * Make code (.cc) documentation optional, only if extends the meaning
 * Use:

Code: [Select]
/*!
 * Doc
 * \param a explanation
 * \param b explanation
 * \return explanation
 */
That information must be mandatory, any new method *HAS* to be docuemnted, and one can't touch a function already in code and leave it undocumented.

 And for ocasional extra explanations in-code, use ///

 I'd stick the documentations in the .h because it looks more natural to me, but said this, I don't mind if we agree in documentating just the .cc. But I'd like to reach one decision and see all the code documented the same way. :)
Title: Re: German in the code
Post by: Dwachs on June 18, 2012, 06:55:17 PM
I would propose to document classes, their member variables and inline member functions in header files. All other functions should be documented in code, to get the code comments as close as possible to the implementation.
Title: Re: German in the code
Post by: eipi on June 18, 2012, 07:50:09 PM
I'd also vote for documenting the headers because you can get a quick overview of what the classes and their functions are doing. If you just want to have a short header file, you could collapse the comments in MSVC / Eclipse / whatever so that they cover a single line only.
However, there will be some comments left in source files documenting static functions or global variables (unless we move their functionality to class methods in the future, of course).

EDIT:

@Dwachs: I know both @return and @returns are valid Doxygen syntax, but Eclipse does not highlight @returns and some other methods were tagged with @return, so I chose this :)
Title: Re: German in the code
Post by: Markohs on June 18, 2012, 10:42:21 PM
 I still think just documenting the includes and just documenting the .cc in things that can't be documented in the .h it's the best option.

 But if Dwachs proposition is chosen, given he menctioned documenting inline functions in the .h, I'll add another clause:

* Virtual methods of classes need to be documented in the super-class .h, and re-documentated in each .cc redefinition.
Title: Re: German in the code
Post by: whoami on June 20, 2012, 06:15:08 PM
Concerning my tool (which is something like a quick hack or prototype): I had little time recently, so not much has changed, and I have only partially evaluated the alternatives.

But I also hesitate to continue, because - with the sparse feedback - I do not know how the chances are that it might be used, or what has to be added, improved or even removed to gain approval. From reading this whole thread, I know many of the requirements that exist for the task, though. If there is already sufficient reason to say "stop, this will not work out", please do, I have not spent very much time on it yet.
Title: Re: German in the code
Post by: Markohs on June 21, 2012, 10:40:49 PM
My personal oppinion is that this project should continue, but it's up to prissi/Dwachs to say the last word imho.

About the documentation decisions we are taking, don't you think it's time to incorporate them to documentation/coding_styles.txt? looks like dwachs is already applying it in the code from what I just saw on last svn commits. I can make a draft if you want.
Title: Re: German in the code
Post by: Dwachs on June 22, 2012, 06:14:33 AM
About the documentation decisions we are taking, don't you think it's time to incorporate them to documentation/coding_styles.txt? looks like dwachs is already applying it in the code from what I just saw on last svn commits. I can make a draft if you want.
Please go ahead :)

It would also be a good idea to come up with a nice header comment like "this file is part of simutrans project under this license see file bla" and make such headers consistent across files ...

@whoami: I am still undecided what to do. I see two interwoven tasks here: translating identifiers and documenting code. Ideally both would go hand-in-hand. So much code, so little time...
Title: Re: German in the code
Post by: whoami on June 22, 2012, 10:31:47 AM
So I understand that my approach is still under consideration. That allows me to continue.
Title: Re: German in the code
Post by: eipi on June 28, 2012, 11:06:18 AM
The translation patches have been updated against r5788. I made some small updates to ./bauer and ./besch.

As to the file header comments: What about something like this:

Code: [Select]
/**
 * This file is under <this particular license>.
 * See "license.txt".
 *
 * @file <filename> <One-sentence description>
 * @author <Author>
 * @date <Last edit date>
 */

Suggestions are welcome (also for the patches :))
Title: Re: German in the code
Post by: Dwachs on June 28, 2012, 01:06:52 PM
The translation patches have been updated against r5788. I made some small updates to ./bauer and ./besch.
Where is the patch file ???

As to the file header comments: What about something like this:
Looks good. The source code is under artistic license. I would leave out @date and @author comments as these will be outdated very soon.

Title: Re: German in the code
Post by: eipi on June 28, 2012, 06:02:59 PM
The above links I posted still work, I'll post them again:

https://dl.dropbox.com/u/53679800/Simutrans/patches/SimuTranslation_bauer.patch
(for the changed files in ./bauer only, because I'm still working on the other parts)

https://dl.dropbox.com/u/53679800/Simutrans/patches/SimuTranslation.patch
(the whole patch)
Title: Re: German in the code
Post by: prissi on June 30, 2012, 08:31:11 AM
The date could be gotten anyway from SVN/git ...
Title: Re: German in the code
Post by: VS on June 30, 2012, 10:02:19 AM
You can add "replace keywords" and set svn to replace these with actual date, revison, name etc. There is no need to add any new tools to the process at all :)
Title: Re: German in the code
Post by: eipi on July 08, 2012, 12:53:32 PM
FYI, both translation patches have been updated against r5811. See my previous post in this thread in order to download them.

@prissi / Dwachs: Can you please make dots at the end of the first sentence? I run doxygen with JAVADOC_AUTOBRIEF which interprets the first sentence until the first dot in a comment as the brief description. It looks a bit weird in the generated documentation.
Title: Re: German in the code
Post by: Dwachs on July 08, 2012, 02:10:36 PM
@prissi / Dwachs: Can you please make dots at the end of the first sentence? I run doxygen with JAVADOC_AUTOBRIEF which interprets the first sentence until the first dot in a comment as the brief description. It looks a bit weird in the generated documentation.
Which one specifically? If you would provide a patch for those annoying missing-dots, it would be changed in ..seconds / hours.
Title: Re: German in the code
Post by: eipi on March 28, 2013, 11:39:59 AM
First of all, sorry for the late reply; I had to do some work for university. I hope this will change in the future so I can put more effort into improving Simutrans.  ;)

@Dwachs:
Sure. The patch file is attached to this post. I only modified comments in /bauer for now. Imho the missing dots can be added to the other files on the fly when translating  and updating comments there.
Furthermore, the patch also includes some minor typo corrections.
Title: Re: German in the code
Post by: An_dz on September 01, 2013, 10:58:48 PM
I think this is the best place to post.

I fixed some typos and translated some German in the gui folder.

I also removed one duplicated include in welt.cc.
Title: Re: German in the code
Post by: kierongreen on September 01, 2013, 11:11:27 PM
Nice work - only reason I'm not going to patch this just now is that there's the GUI Theme Patch (http://forum.simutrans.com/index.php?topic=11956.msg123455#msg123455) being developed at the moment and I fear this would probably conflict in a few places...
Title: Re: German in the code
Post by: An_dz on September 02, 2013, 12:45:02 AM
No conflicts here, and it might help Max, he doesn't read German. Not that I know much :p.
Title: Re: German in the code
Post by: An_dz on September 03, 2013, 05:13:16 PM
Patches for docs, display and vehicle folders.
Title: Re: German in the code
Post by: Dwachs on September 04, 2013, 07:47:23 AM
I fixed some typos and translated some German in the gui folder.

I also removed one duplicated include in welt.cc.
Thank you! In r 6671. You fixed some prety epic typos.

Edit:
Patches for docs, display and vehicle folders.
Now in r6672 & 6673.
Title: Re: German in the code
Post by: An_dz on September 04, 2013, 09:02:23 PM
Thank you! In r 6671. You fixed some prety epic typos.
*pretty ;D

Now in r6672 & r6673
I found I wrongly translated one string in vehikel, will be fixed on next set of patches.
Title: Re: German in the code
Post by: Dwachs on September 05, 2013, 07:47:13 AM
The best typo was: cooledcted -> collected. And not to forget: crossong, where somebody suggested cross-song :P
Title: Re: German in the code
Post by: whoami on September 05, 2013, 09:12:05 AM
Ah yes, the well known cross-singing!
"Let's do the time warp agaaaaain..."
Title: Re: German in the code
Post by: An_dz on September 05, 2013, 01:05:26 PM
The best typo was: cooledcted -> collected. And not to forget: crossong, where somebody suggested cross-song :P
Haha. Yeah, I did some shits.
At least I'm forcing you to translate, and clean, the comments. :D
Title: Re: German in the code
Post by: Max-Max on September 08, 2013, 02:37:24 PM
@An_dz
Thank you for the translations :thumbsup: I do appreciate it!

@kierongreen
Nice work - only reason I'm not going to patch this just now is that there's the GUI Theme Patch (http://forum.simutrans.com/index.php?topic=11956.msg123455#msg123455) being developed at the moment and I fear this would probably conflict in a few places...

There is a new patch coming up soon, fixing the half scrollbars... I suggest any pending patches to be implemented together with it.
Title: Re: German in the code
Post by: eipi on September 17, 2013, 02:44:30 PM
More translations on the way... :)

I cleaned up some code and translated comments in roadsign_t and signal_t.

Patch against r6720.
Title: Re: German in the code
Post by: kierongreen on September 17, 2013, 04:53:02 PM
That's a lot of translations! Some I think are great (zustand to cur_state for example, although I'd actually probably just use state) others I'm not so sure of. weg to way and str to road for example - I think if we are doing this then possibly we should consider translating class names as well to make sure code is consistent.
Title: Re: German in the code
Post by: Ters on September 17, 2013, 06:16:08 PM
The time must surely be now, when much of the code is in turmoil anyway. There might not be a stable release this year at all. (We could do a release, but more of a WIP release than a stable release.)
Title: Re: German in the code
Post by: Markohs on September 17, 2013, 07:09:47 PM
Agree, lots of deep changes in the code means we can mess with it even more. ;)
Title: Re: German in the code
Post by: eipi on September 18, 2013, 01:38:44 PM
That's a lot of translations! Some I think are great (zustand to cur_state for example, although I'd actually probably just use state) others I'm not so sure of. weg to way and str to road for example - I think if we are doing this then possibly we should consider translating class names as well to make sure code is consistent.

I'm all for translating class names, too, however with the gui theme patch being developed, I am against changing too much. I don't want Max-Max have to rewrite half of his patch because of that.

Btw, forgot to include the changes to simvehikel.cc. The new patch fixes this.
Title: Re: German in the code
Post by: prissi on September 18, 2013, 02:17:32 PM
I would also suggest state.

Why were correct comments remove from the cc files? (Most were trivial, but still ... )
Title: Re: German in the code
Post by: Markohs on September 18, 2013, 02:27:34 PM
I think he moved the comments to the .h, that's the place they should be
Title: Re: German in the code
Post by: Ters on September 18, 2013, 03:40:09 PM
I think he moved the comments to the .h, that's the place they should be

For a library, I would agree, but for an application, I don't see anything weighing up for the hassle of having to swap back and forth between header and source when coding and reading/updating comments.
Title: Re: German in the code
Post by: Markohs on September 18, 2013, 04:06:46 PM
Well, we decided to do it that way months ago, you could also say you don't like to browse .cc files when you are just looking at the .h of a class. no? :)
Title: Re: German in the code
Post by: Ters on September 18, 2013, 04:47:08 PM
Well, we decided to do it that way months ago, you could also say you don't like to browse .cc files when you are just looking at the .h of a class. no? :)

The eternal curse of C. I'm thankful that I program Java for a living, and not C or C++. (There is still an issue of having documentation on the interface, but IDEs are generally much better for Java, at least the free ones.)
Title: Re: German in the code
Post by: prissi on September 18, 2013, 09:23:42 PM
Honestly we never decide on anything. I still prefer (and add) comments at both locations, especially when the main routine is almost comment free. One could as well argue, that when you slightly change the implementation, you could easily forget the h file and end up with outdated comments. A matter of taste aparently.
Title: Re: German in the code
Post by: Markohs on September 18, 2013, 11:26:44 PM
iirc, we decided to document all methods in the .h, with the exception of static functions or comments in-code that will ofc be in the .cc.

Duplicating documentation in the .h and .cc is a very bad idea, and the motivation is, as you said, it's that's allways a bad idea to have two copies of the same thing, because they will get out of sync easily.

Can't we get a definitive agreement in a so important area like this one? All open source projects have reached a agreement. Specially when some things here seem to be written in stone and others seem to change often, depending of the wind that blows.
Title: Re: German in the code
Post by: Ters on September 19, 2013, 05:53:00 AM
All open source projects have reached a agreement.

I took a look at some of the open source C/C++ code I have, and some of them didn't seem internally consistent in this regard.

For those that had what I would call systematic documentation, it was about an even split (though the sample size was small) between projects that placed the documentation with the declaration (in other words almost exclusively in header files) and those that placed it with the definition (in other words split between header and source). These were all libraries. It might be that some try to keep headers as compact as possible to reduce compilation time for their users, which may or may not be a real issue.

Those that didn't have systematic documentation, didn't have much documentation in header files. Sometimes they documented groups of functions with a single sentence, a sentence that might have nothing to do with what they did, but sometimes things like why they were declared at this particular point in the header.
Title: Re: German in the code
Post by: kierongreen on September 19, 2013, 07:17:15 AM
Summary in the .h any detailed comments in .cc would be my suggestion...
Title: Re: German in the code
Post by: Markohs on September 19, 2013, 07:27:27 AM
 All this discussion about documentation, that doesn't look like it's ever gonna reach a agreement, just makes developers that really want to have a properly documentated source code feel frustrated.

 I have myself tried to properly translate,comment and clean up some of the game files in the past, and commited to trunk, simworld_t, loadingscreen_t, savegame_t and inherited classes... And maybe some more I can't remember. I know it was not a perfect job, and I saw they were made even better in patches posted here. I feel now like I wasted my time.

 Well yes, I guess not all open sourced projects have excelent documentation policies, but for example GNU developed software all follow some guidelines, strict in some places.

 I just wanted to express the lack of a defined way of doing things it's just making things worse, for everyone.

 It's strange how we can have so vague guidelines on documentation but it's commonly accepted here that:

 * You can't use any technology that was not present in the 1990s
 * Don't use namespaces
 * Don't use any OO design pattern
 * Methods that span 800 lines of code are ok, they are even prefered
 * Virtual functions are evil and shoudn't be used anywere
 * It's ok to make one class take multiple responsabilities, it's prefered.
 * Globals are not that bad, extern is ok.
 * We use C++, but that was maybe a bad decision, we could have keeped ourselves in C
 * Refactor is bad and evil, breaks patches that I might have hidden somewere
 * ...

 I'm just exaggerating a bit, I know that's not 100% true, and some of those things are slowly changing. I just wanted to show how inflexible are you with some things and how vague you are in others.

 You know what I mean? :)

 I know I'm getting off-topic, but I'll just lik this: SOLID (http://en.wikipedia.org/wiki/SOLID_%28object-oriented_design%29)
 
Title: Re: German in the code
Post by: prissi on September 19, 2013, 10:27:00 AM
Properly documented sourcecode is not a waste of time. But this goes beyond writing just a oneliner what a function will do (which was for instance a lot of the 3.6.x OpenTTD sourcecode).

And as said before, this is open source. I committed in the past stuff I did not like and will do it in the future. I am not happy to be a "leader". I voice my option and then you can either commit or not.

Many of the 90ies technology in simutrans is due to Simutrans actually made in the 90ies. Until five year ago half of the files were C files, so you could not use variable definitions but at the top of the function. It took a month to have a full working version with *.cc files.

Hence a lot of global, because of C. Nowadays the number of globals is much less.

About half of the code has its origin by people who never had any formal education in programming techniques (or none at all, like me). Furthermore, programming techniques are changing all the time. If you want your code only for specialist, use complex structures. You want as many people to have at least a chance to follow: Avoid too complex stuff, or less portable (not every platform has the latest compilers). I think you would agree on that.

So what is complex: Some stuff makes code difficult to follow. For me many short functions are more difficult (I think kieron said something like this too) while you prefer many short ones. Namespaces are tricky because they may or may not overlay functions (same as operators). Otherwise they just add more letters, but if this helps understanding ... It never came really up.

virtual functions can make the code much cleaner and hence easier, so it is preferred if you use them together with inheritance and unknown stuff. ding_T is a classical implementation of inheritance and virtual functions, or?

Does "multiple responsabilities" means reusing code? When did this became a bad thing?

Refactoring is not bad, although not trivial. If trivial do it. (Or do you mean beautifying? I would like to do this today, but then experimental might get impossible to merge, even if it does the same. patches could be applied and then beautified.)
Title: Re: German in the code
Post by: Markohs on September 19, 2013, 12:28:47 PM
Properly documented sourcecode is not a waste of time. But this goes beyond writing just a oneliner what a function will do (which was for instance a lot of the 3.6.x OpenTTD sourcecode).

 Well, we agree here. :)

 But anyway a oneliner is better than nothing at all.

And as said before, this is open source. I committed in the past stuff I did not like and will do it in the future. I am not happy to be a "leader". I voice my option and then you can either commit or not.

 I know you submited code you didn't liked 100%, and I've submited code that's not of your taste too. I've seen it and I appreciate that. I know you want the best for the game.

 I'd say for example here, this was a very good idea:

http://forum.simutrans.com/index.php?topic=12447.0 (http://forum.simutrans.com/index.php?topic=12447.0)

Many of the 90ies technology in simutrans is due to Simutrans actually made in the 90ies. Until five year ago half of the files were C files, so you could not use variable definitions but at the top of the function. It took a month to have a full working version with *.cc files.

 That's true too. But you (and not only you) have to mind that you have been vehemently against:

 * STL library
 * boost libraries
 * c++ 11 features
 * Anything that doesn't compile in Haiku/AmigaOS (does anybody still use that nowadays?)

 I'm not against making our own classes when required, but only if they come with something of value to the project (performance, for example, in the places that it's really needed).

Hence a lot of global, because of C. Nowadays the number of globals is much less.

 Yes, there are less, but they should be zero in the future. :)

About half of the code has its origin by people who never had any formal education in programming techniques (or none at all, like me). Furthermore, programming techniques are changing all the time. If you want your code only for specialist, use complex structures. You want as many people to have at least a chance to follow: Avoid too complex stuff, or less portable (not every platform has the latest compilers). I think you would agree on that.

 I agree partially.

 Not having formal in education it's something noone with a bit of brain whould use to undervalue any work, in fact I admire in how well our code works, and how stable its.

 What I can't understand is why from that point of view, computing engineer's widely accepted designs and coding styles are underrated sometimes, just because they are not liked or seen as "complex".

 I know some of this coding patterns, come and go, and many have proved to be not really working or unnecessarily complicated. But many are still considered as successful strategies to code and arrange a system, and that will not change in the future, they are accepted and best options to code nowadays, and better than old primitive designs, not object-oriented.

So what is complex: Some stuff makes code difficult to follow. For me many short functions are more difficult (I think kieron said something like this too) while you prefer many short ones. Namespaces are tricky because they may or may not overlay functions (same as operators). Otherwise they just add more letters, but if this helps understanding ... It never came really up.

 About following code, we already talked about that once, it's very hard to program without an IDE.

 About namespaces, they don't do miracles and have their downsides, but they must be useful when modern languages like java makes them mandatory, more or less.

 Code has to be simple, systems need to be too. Every programmer should aim to the simplest piece of code that acomplishes the objective. But don't get me wrong, it's not simple because doesn't use complex artifacts, it's because it's based on a simple idea, even it's maybe more complex in details.

 Never designed something in a first sight that was simple, started coding it, and noticed it was getting so full of small complex details that you end throwing that idea to the trash to start with another simpler design, in idea?

 A simple system is the one that lacks complex details. Better to move this details to another layer where they are handled in a simplier way.

 Very often the simplest designs, the best ones, are very very hard to find.

virtual functions can make the code much cleaner and hence easier, so it is preferred if you use them together with inheritance and unknown stuff. ding_T is a classical implementation of inheritance and virtual functions, or?

 Yes, that part is.

Does "multiple responsabilities" means reusing code? When did this became a bad thing?

 No, it means the class is doing too much stuff, and should be split.

 Let's put karte_t as an example, right now:

* Contains the world elements (tiles, heights)
* Handles all world modification mechanisms
* Controls the world time
* Contains the outer part of world simulation code
* Handles the cursor movement
* Receives user events, mouse and keyboard
* Has the main game loop karte_t::interactive
* Handles the multiplayer sync logic
* Is able to generate semi-random maps
* Controls the camera viewport
* Handles the game sounds
* Handles seasonal changes
* Stores world records
* Has load/save logic

 I think I'm missing some things, and some might be partially true. Is this simple? I'd say absoultely not.

 I don't think we are reusing code here, we just made a class too big because we never tried to factor this funcionalities in sub-systems.

 Many engineers think a class just should have one responsability, I think maybe that's too strict, but certainly it should not do more than two things, and they have to be tightly related. Why? Because it's very hard to modify a so complex class without breaking anything, everytime you touch simworld.cc you risk yourself to break one or many of those funcionalities.

http://en.wikipedia.org/wiki/Single_responsibility_principle (http://en.wikipedia.org/wiki/Single_responsibility_principle)

Refactoring is not bad, although not trivial. If trivial do it. (Or do you mean beautifying? I would like to do this today, but then experimental might get impossible to merge, even if it does the same. patches could be applied and then beautified.)

 We've as a team refacored quite a lot of things this year, and experimental programmers have integrated the changes very efficiently, I think they will survive. ;)
Title: Re: German in the code
Post by: prissi on September 19, 2013, 01:03:20 PM
STL and boost ... boost did not work properly on mingw when first proposed, and I am not sure about phones etc. And personally I feel insulted when distributing a libary which is larger than the actual program. And it is another libary which make contribution again more difficult, especially since you have to compile it yourself if not using msvc aparantly.

STL is mostly available since 2005 or so, 7 years after the first simutrans release. About 80% of the structure was there, including most templates. Simutrans list templates also waste less memory (and are hence potentially faster). So why go through hassles with STL which was implemented slightly different on Haiku (and may be different incomplete on other platforms). Why bother, when things work and are more portable?

And honestly, the C++11 features like auto (urg, have fun guessing what type this is), or enums which cannot convert to int: I feel how this can improve simutrans code readabilty.

Over the years I have programmed for six or seven (how you count the MACs) different platforms, and even simple C code without any special libaries always needed modifications. The more libaries and complex header we rely on, the less likely a port will be. And we are aiming for ARM now, or at least that is one of the ideas of the theme manager to use for.

About karte_t: This is tricky. karte_t avoids a lot of globals. And thing got into karte_t since they are part of a map. There was once a try to seperate the display system, i.e. karte_ansicht_t in simcview. But Hajo never really finished it. I admid, handling tools is not needed to be done by karte. That part could be as well done by something else, probably some child of karte (since it will need to acces an awful lot of karte). So it may work out a a map, from which display, interaction and other stuff is derived. (And Unfourtunately all have to be interwoven, i.e. tools need to know about timing and so on.)

I am open for suggestions ...
Title: Re: German in the code
Post by: Markohs on September 19, 2013, 03:17:59 PM
What if I want to use a structure not already in simutrans, I have to code it myself? I wonder how many structures are stored in simutrans with a structure "similar enough" to what the programmer really wanted, just to not having to implement it from scratch. :)

What's in use, can remain that way, but makes no sense having to restrict ourselves to the current data structures, even Playstation 3/wii/android have a STL implementation, why not allowing its use?

Well, you can also say libraries make your code more portable, since for example with SDL you can abstract yourself from many details.

But well, let's just leave this discussion here, I just wanted to point how inflexible are we on some subjects and how loose are for others, for example documentation. :)

About the suggestions, I'm working on a quite complete refactoring of all simutrans code, introducing singletons, managers, a task scheduler and more changes (inspired/copied from Ogre3D, a book (http://www.amazon.com/Game-Engine-Architecture-Jason-Gregory/dp/1568814135) and some internet articles). When I have something more decent to show I'll post it, don't wanna scare you yet, I hope many of the ideas are welcome, and we reach a agreement to get that design (at least partially) in the game. :)
Title: Re: German in the code
Post by: kierongreen on September 19, 2013, 05:24:51 PM
Parts of simutrans are very speed critical - it makes no sense refactoring parts of the code if this slows the game down significantly. This is one reason why c (and c like code) persist.

Regarding long functions - I'm all for breaking these up when doing so reduces code duplication or divides an unwieldy 800 line function into neat sections. I'm don't support dogmatically splitting functions into screen sized pieces just because that's how things should be. Some functions in simutrans are naturally 200 lines long. Splitting them will just create unnecessary overheads, and make the program difficult to follow.

To clarify my opinions on documentation - .h files should describe what a function does, .cc files should describe how a function works (if it's not obvious).
Title: Re: German in the code
Post by: Ters on September 19, 2013, 05:46:56 PM
Ogre3D is not an example to follow in my opinion. I hated programming against it, always feeling unsecure of whether I needed to explicitly free/close/destroy something, or whether some manager did it for me. It would have worked a bit better in a managed language like C# or Java. I seem to recall some hidden singletons, which you had to construct with new, but which then lived on as a singleton. It's possible that I remember that from CEGUI, which was even worse.
Title: Re: German in the code
Post by: prissi on September 19, 2013, 08:32:12 PM
If one really wants proper OOP (whatever this is, this seems to change a lot every ten years ... ) then properly one should rather reimplement Simutrans in Java: Full portability, Garbage collection, standadized GUI, graphics, network code, Android "native" ...

Maybe singletons will be considered the worst idea of OOP in ten years. (Just as a provocative teaser.)

The same argument about templates can be used about the GUI and almost any part of the program. But I am sure, after ten years any program will look old to anybody who comes with the current "state of the art" knowledge. When I started simutrans coding, it did not even compile on MSVC.

That said, we are slowly going towards a better readable code, or?
Title: Re: German in the code
Post by: eipi on September 19, 2013, 08:59:37 PM
To clarify my opinions on documentation - .h files should describe what a function does, .cc files should describe how a function works (if it's not obvious).

I like this - though this has the risk of duplicate comments in .h and .cc files. In my opinion in .h files should give a quick overwiew of the "capabilities" of the class, while documentation in .cc files can be done either directly in code, or at the start of the function if the algorithm needs an overall description.

As to translating and refactoring code - What about focusing on non-gui-related classes like ding_t and derived classes for the time being and wait until the gui theme patch is in place? For example ding_t::ist_entfernbar() can be refactored to ding_t::is_removable(); this does not interfere with the gui as far as I can see.
Title: Re: German in the code
Post by: Markohs on September 19, 2013, 10:54:53 PM
Ogre3D is not an example to follow in my opinion. I hated programming against it, always feeling unsecure of whether I needed to explicitly free/close/destroy something, or whether some manager did it for me.

 Well, I had a similar feeling at some times too. I think this can be mitigated on many ways, for example:

* if you get a object as a result of a manager call let's say (just an example) log_t logmanager_t::get_logger(...):
  + if you want to stop using it, you need to logmanager_t::destroy(log)
  + when the manager is destroyed, he'll automatically destroy al logs not destroyed already.
 * you supply a object to a manager, you are responsable of deleting it afterwards, because the manager will copy it if it needs to.

 Dunno, I'll see what I can figure, some rule of thumbs, because what I don't really want to do is use smart pointers nor garbage collection.

It would have worked a bit better in a managed language like C# or Java.

 Yep, as you know it's one of the problems derived from the absolute flexibility in C++, memory management is 100% manual.

I seem to recall some hidden singletons, which you had to construct with new, but which then lived on as a singleton. It's possible that I remember that from CEGUI, which was even worse.

 Yep, that should not happen. I'm exploring a root_t:: singleton where *all* managers are created in the correct order and destroyed accordingly in shutdown.

 I'm also for example thinking if objects like umgebung_t need to be turned into singletons too, I like how umgebung_t works in current code, the problem is having to declare each static member in the .cc *also*, but the alternative is turning all:

if(umgebung_t::mute_midi)

into:

if(umgebung_t::get_singleton()->mute_midi)

 So I think I'll maybe let that class stay as it is now.

 Well, lots of things to experiment, if you want to have a look I can post the patch, but it's basically tests now, trash. :)

 Dunno, let me do more experiments, maybe this all will end in the trash bin. :)

If one really wants proper OOP (whatever this is, this seems to change a lot every ten years ... ) then properly one should rather reimplement Simutrans in Java: Full portability, Garbage collection, standadized GUI, graphics, network code, Android "native" ...

 Yes, a modern language like java that makes objects mandatory and has garbage collection makes easier to program OO, but neither java nor C# give the performance C++ gives. From what I read all commercial games are written in C++, and use OO design, but ofc, and like kierongreen comments, performance critical parts have to remain a bit C-style.

Quote
Maybe singletons will be considered the worst idea of OOP in ten years. (Just as a provocative teaser.)

 Hehehe, yep, maybe. The good thing about singletons, is, to start with, you can be 100% sure they are instanced just once, and having one singleton containing the rest of singletons you can control in which order they are created/deleted.

 I'm following "Game engine Architecture" From Jason Gregory, Chapter 5.

 tip: google "game engine architecture" , at least on my computer the fourth entry it's a pdf with that book, legal or not. But I have the book in paper, for the case the big boss is watching.

Quote
That said, we are slowly going towards a better readable code, or?

I think so, specially this last year, as a team effort, everybody it's making code cleaner. I'm happy about it. Specially Dwachs imho, that writes very clean code.
Title: Re: German in the code
Post by: Markohs on September 19, 2013, 10:55:57 PM
To clarify my opinions on documentation - .h files should describe what a function does, .cc files should describe how a function works (if it's not obvious).

 I think this is very reasonable. I agree.

As to translating and refactoring code - What about focusing on non-gui-related classes like ding_t and derived classes for the time being and wait until the gui theme patch is in place? For example ding_t::ist_entfernbar() can be refactored to ding_t::is_removable(); this does not interfere with the gui as far as I can see.

 I'd say go ahead. But, are you planning to just rename methods/variables? Or are you renaming the classes and files (with the Makefile and VS project) too?
Title: Re: German in the code
Post by: Ters on September 20, 2013, 05:04:47 AM
Maybe singletons will be considered the worst idea of OOP in ten years. (Just as a provocative teaser.)

I've seen this already happen. The argument is that singleton is just a gloified global variable, and global variables are bad (according to purists).

you supply a object to a manager, you are responsable of deleting it afterwards, because the manager will copy it if it needs to.

The problem is that, especially with the kind of data structures Ogre3D operates on, copying might be forbiddingly expensive. There are also issues with instance sharing, so should the copy be deep or shallow. I feel that Ogre3D has chosen a strategy that they for practical reasons can't really follow (or so they believe at least), so they end up with the worst of both worlds.
Title: Re: German in the code
Post by: Miziiik on September 20, 2013, 10:21:16 AM
I already thought about reimplementing Simutrans in Java because good portability (mainly for Android). It should be easier to port Simutrans to Android with Java. If someone would use OOP it's easier to do it in Java than in C++. Java isn't  memory-intensive when code is clear. I think that Simutrans should't be memory-intensive in Java if the code will be clear.
Title: Re: German in the code
Post by: Markohs on September 20, 2013, 11:02:14 AM
Seeing java performance you'll have quite of a problem keeping it running smooth in that platform, I think. But it depends on map size and density of graphics on screen mainly, we need to figure how to make the game consume less CPU, I think.
Title: Re: German in the code
Post by: Miziiik on September 20, 2013, 11:28:00 AM
Umm you're right. With big map and a lot of graphics on the screen it will maybe be more memory-intensive and use a lot of CPU. But with C++ it's harder to port to ARM. We can use other languages but it's a lot of work to reimplement Simutrans to that language.

A question to C++ programmers: Is OOP in C++ faster/better for Simutrans or not? About C# you're right with performance too. I learned C# and now I'm not using it. Now I think about "learning" java or C++ or other language but don't know what should I choose...
Title: Re: German in the code
Post by: Markohs on September 20, 2013, 11:52:10 AM
I don't really know why you and some others say porting C++ to ARM is harder, ARM is just a processor, and there is a ARM version of GCC. Where is the problem? :)

If we bring more OOP to simutrans, it will be to rearange code into more understadable units, simpler to understand and interchangeable/portable, nothing more.
Title: Re: German in the code
Post by: Ters on September 20, 2013, 02:47:43 PM
If we bring more OOP to simutrans, it will be to rearange code into more understadable units, simpler to understand and interchangeable/portable, nothing more.

I find Simutrans quite neatly divided into units, except perhaps a few bits around the world, but I've read on this forum that some of that has changed since last I looked at it. The few things that aren't in classes actually ease porting in my opinion, since one can just replace a few functions rather than have to have interfaces and factory methods, or some hacks that are far worse.
Title: Re: German in the code
Post by: Markohs on September 20, 2013, 02:58:42 PM
Well, you can allways create one static object with static functions/members for each .cc that doesn't use objects.

simmain_t, simevent_t, simsys_t, simgraph_t... I think that list can be pretty huge. But it's possible. The scripting part with squirrel can be a problem too, maybe.
Title: Re: German in the code
Post by: Ters on September 20, 2013, 03:18:22 PM
It's possible, but it's fake OOP in my opinion. Kind of like in the South Park movie where the kids were told to say poo instead of ****. Nothing has changed, the code is still effectively organized the same way, there has just been added some OOP-ish keywords around it. And you have to write simgraph_t::draw_line rather than display_draw_line. (Or perhaps add a using. I don't remember if that works with anything but namespaces in C++. I always felt that using using defeated the point of namespaces.)
Title: Re: German in the code
Post by: prissi on September 20, 2013, 04:53:08 PM
About ARM: First simutrans code works Bigendian as well as little endian. (For the PowerMac version be had done this). On Android, as far as I know, the y use the (stupid) Intels byte-twist endianess, so it shoudl work too. The onlz thing different on ARM is that words must be alinged.

Anyway, simutrans has been compiled for Android, so it works.

So concepts like multiple inheritance used in simutrans (mainly the sync_step and the GUI callbacks) would not work in JAVA. I am also not sure how efficiently store objects on tiles with a garbage collector.
Title: Re: German in the code
Post by: Ters on September 20, 2013, 06:19:34 PM
So concepts like multiple inheritance used in simutrans (mainly the sync_step and the GUI callbacks) would not work in JAVA. I am also not sure how efficiently store objects on tiles with a garbage collector.

I miss multiple inheritance in Java sometimes. They've sort of snuck it in in Java 8, though.

The garbage collector has nothing to do with efficient storage as far as I know. For storage, you can just envisage always having to use new for everything but primitives (char, int, boolean, etc.). There are some crazy alternate ways of allocating memory in Java, but I'm not sure it works for anything but primitive arrays (I've usually heard of just arrays of bytes).
Title: Re: German in the code
Post by: eipi on September 20, 2013, 08:26:13 PM
I'd say go ahead. But, are you planning to just rename methods/variables? Or are you renaming the classes and files (with the Makefile and VS project) too?

Well, if I'm already translating it would make sense to also rename class names along the way. But we rather should do this in small steps. My next goal is to rename ding_t and methods, post a patch with these changes here and then work my way down to all classes derived from ding_t.
(I guess ding_t should be renamed to thing_t.)

What do you think about it?
Title: Re: German in the code
Post by: kierongreen on September 20, 2013, 08:56:31 PM
I'd say obj_t to replace ding_t. Currently we have wayobj_t, groundobj_t and movingobj_t all being ding_t so making obj_t the generic class would seem to make some sense to me.

Although the argument against this is that there is a tabfileobj_t (used with tabfile_t).

Also thing_t (while I appreciate it is a literal translation of ding_t) sounds rather generic and... weak?
Title: Re: German in the code
Post by: prissi on September 20, 2013, 09:23:34 PM
Kireons idea is great, as the description (besch) is called obj_besch_t ...
Title: Re: German in the code
Post by: kierongreen on September 20, 2013, 09:47:58 PM
Bringing up the questions of what besch should be. Description is too long, ideas:
desc(ription)
def(inition) - directory would be defs?
type
class
header
?

Also, bauer to builder?
Title: Re: German in the code
Post by: prissi on September 20, 2013, 09:57:24 PM
bauer is rather a manager, sicne it maintains the static lists and tools.

bsch -> desc (unique and short)
Title: Re: German in the code
Post by: sdog on September 21, 2013, 03:19:08 AM
This thread suddenly became very interesting. Just learned a lot of new concepts by looking up what you're discussing in wikipedia. Thanks for that.

One OT question though: I don't understand why global variables are bad could someone tell why. Not a rethorical question, i believe you they are. It would be nice to know why.

I tend to use them from time to time in perl. (I wish there were some in f77 using something like main:parameter would be much nicer then includes of files with definitions or common blocks.)
Title: Re: German in the code
Post by: Markohs on September 21, 2013, 03:56:59 AM
I understand obj_t makes complete sense reading your comments, and it does.

Anyway I'd like to suggest:

base_domain_obj_t
base_obj_t

 because obj_t doesn't give enough information about that's the class about, the other names give a hint it's part from the "runtime object model", and base because it's the root of hierarchy. root_obj_t is a good name too.

 I whoudn't say no to obj_t , but I feel like it's too short, and lacks context, meaning. :)

This thread suddenly became very interesting. Just learned a lot of new concepts by looking up what you're discussing in wikipedia. Thanks for that.

 Good, I feel a little bad because we are on offtopic, but I don't really know if splitting the topic is worth it. :)

One OT question though: I don't understand why global variables are bad could someone tell why. Not a rethorical question, i believe you they are. It would be nice to know why.

 The problem they have is since they are readable/writable by virtually any part of the code, you have  absolutely no idea who's modifying them in runtime, you have no way of controlling acces to it.

 At a pratical level, if it's a global function (simutrans has a lot of that), you can allways debug and see on the stack from where in the code that routine was called from, but you can't do that on a variable. It's just calling for trouble, because if a bug related to that variable arises, you have absolutely no way to debug that, just looking at the code.

 Why are they used? Because it's very easy to reach that vaiable, it's way easier than modifying a member variable of a class, ( a public class static member attribute is in that sense also a global variable, and a variable inside a namespace too), and performance-wise it's the fastest way to access a variable.

 When you program, it's better to restrict your code to access variables inside a restricted namespace, ideally code should only modify variables on its own class, or declared inside te function (or parameters), the smallest the scope of variables your code touches, the less you have to take into account when designing and modifying your code.

 Think of a donkey, those things they had on the eyes to see only what they had in front of them, to not get distracted by the envirnment. It's a metaphor, but you as a programmer, should read code as if you were wearing that.

(http://connuestroperu.com/images/stories/animales/caballoanteojeras1.jpg)

 if you are a disciplined programmer you know the function you have in front of your eyes only modifies variables you have in front of your eyes. If it accesses global variables, it could be interacting with code far away from what you are looking to, virtually anyewre, any .cc file could be accessing that variable too.

 But global variables have their use, I use them sometimes, mainly when scripting, like you, in perl, or bash. But my oppinion is you should never ever use a global variable in C, under any circumstances, there is allways a better way to do it, even if it's at the cost of a few CPU cyles or memory accesses. It's a question of time you'll get a bug there. Modern languages like Java for example, don't even have a "global variable" concept, you have to fake it with singletons.

More wiki links, interesting related to this:

http://en.wikipedia.org/wiki/Scope_%28computer_science%29 (http://en.wikipedia.org/wiki/Scope_%28computer_science%29)
http://en.wikipedia.org/wiki/Namespace (http://en.wikipedia.org/wiki/Namespace)

 Sorry for the long post, I hope I didn't bore you. ;)
Title: Re: German in the code
Post by: eipi on September 21, 2013, 08:05:32 AM
I understand obj_t makes complete sense reading your comments, and it does.

Anyway I'd like to suggest:

base_domain_obj_t
base_obj_t

What about simobj_t?  Otherwise obj_t seems OK for me too.
besch -> desc is a good idea.

Ideas for classes derived from ding_t:
(async)_wolke_t -> (async)_cloud_t
baum_t -> tree_t
ding_no_info_t -> (sim)obj_no_info_t
dummy_ding_t -> dummy_(sim)obj_t (or deprecated_(sim)obj_t or maybe a translation which points out this ding is ignored?)
gebaeude_t -> building_t
leitung_t -> powerline_t
raucher_t -> (I don't really know. smoker_t sounds bad :D)
vehikel_basis_t -> base_vehicle_t?
verkehrsteilnehmer_t -> traffic_t
Title: Re: German in the code
Post by: prissi on September 21, 2013, 08:38:07 AM
verkehrteilnehmer includes pedestrians. As it is not used that frequently, maybe independent_vehicles and vehikel then to convoi_vehicle_t?

base_obj_t is for me not more informative that obj. Since this is used all over at countless places, why not call it obj?t. If we go from german to english, we should take advantage of the shorter words in this language compared to german.
Title: Re: German in the code
Post by: Ters on September 21, 2013, 08:40:47 AM
The problem they have is since they are readable/writable by virtually any part of the code, you have  absolutely no idea who's modifying them in runtime, you have no way of controlling acces to it.

 At a pratical level, if it's a global function (simutrans has a lot of that), you can allways debug and see on the stack from where in the code that routine was called from, but you can't do that on a variable. It's just calling for trouble, because if a bug related to that variable arises, you have absolutely no way to debug that, just looking at the code.

 Why are they used? Because it's very easy to reach that vaiable, it's way easier than modifying a member variable of a class, ( a public class static member attribute is in that sense also a global variable, and a variable inside a namespace too), and performance-wise it's the fastest way to access a variable.

 When you program, it's better to restrict your code to access variables inside a restricted namespace, ideally code should only modify variables on its own class, or declared inside te function (or parameters), the smallest the scope of variables your code touches, the less you have to take into account when designing and modifying your code.

 Think of a donkey, those things they had on the eyes to see only what they had in front of them, to not get distracted by the envirnment. It's a metaphor, but you as a programmer, should read code as if you were wearing that.

(http://connuestroperu.com/images/stories/animales/caballoanteojeras1.jpg)

 if you are a disciplined programmer you know the function you have in front of your eyes only modifies variables you have in front of your eyes. If it accesses global variables, it could be interacting with code far away from what you are looking to, virtually anyewre, any .cc file could be accessing that variable too.

 But global variables have their use, I use them sometimes, mainly when scripting, like you, in perl, or bash. But my oppinion is you should never ever use a global variable in C, under any circumstances, there is allways a better way to do it, even if it's at the cost of a few CPU cyles or memory accesses. It's a question of time you'll get a bug there. Modern languages like Java for example, don't even have a "global variable" concept, you have to fake it with singletons.

You touch on, but as far as I could see don't explicitly refer to the concept of no side effects. For readability, debugability and maintainability, a function should (ideally) only read its parameters and only write its return value. For objects in OOP, I assume (I don't think I've ever read it somewhere, but nothing else makes sense to me) methods (called member functions in C++) can modify the object's fields (member/instance variables).

Globals are also troublesome in terms of multithreading, especially when there are multiple CPUs or CPU cores with their own caches. Unless you explicitly synchronize the caches, which has a negative impact on performance, different threads may read different values from the same variable. This is in fact not restricted only to globals, but all mutable objects shared between the threads. The current best practice seems to be to never share mutable objects between threads, and non-constant globals are such a shared mutable object. Trying to follow this best practice may however lead to performance problems due to lots of copying of objects, depending on the application. For practical reasons, little to no production code adhere to textbook examples.

(This is almost like on the road, where everybody knows the speed limit (most of the time anyway), but almost always break it slightly. The few who do keep the speed limit stir up anger from some of the other drivers.)
Title: Re: German in the code
Post by: kierongreen on September 21, 2013, 10:32:07 AM
Quote
If we go from german to english, we should take advantage of the shorter words in this language compared to german.
Completely agree with this :)
Title: Re: German in the code
Post by: Markohs on September 21, 2013, 12:03:49 PM
What about simobj_t?  Otherwise obj_t seems OK for me too.

 I like simobj_t, perfect!

 I also prefer shorter names, but I prefer to have a descriptive name than a cryptical one, making a class named obj_t is like having a variable named "var".

Code: [Select]
void f(char var)
{
   new obj_t obj;
   obj->set_var(var)

 Lacks context, what are we doing?

 It's not like you are gong to type the full name, you'll just select it from the dropbox once you are typing it on your IDE. I think you guys would completely hate programming java. :)
Title: Re: German in the code
Post by: Ters on September 21, 2013, 02:04:29 PM
I like simobj_t, perfect!

I also prefer shorter names, but I prefer to have a descriptive name than a cryptical one, making a class named obj_t is like having a variable named "var".

I thought the same about obj_t. simobj_t seems to capture the fact that this base class is limited to simulated objects, or rather object simulated as distinct entities, since passengers are simulated, but not as a crowd, not as distinct entities.

It's not like you are gong to type the full name, you'll just select it from the dropbox once you are typing it on your IDE. I think you guys would completely hate programming java. :)

My Java IDE autocompletes wonderfully, my C++ IDE only occasionally and not as elegantly, often suggesting things that don't fit the context. At work, I actually deal with Java class names in excess of 60 characters, not including namespace (packages in Java terminology). If we don't keep the path into which we check out the source code short, some of these files can't be deleted by Windows (except through subst-ing) as the path is too long. (It's strange how creating the files is never a problem.) But as an amateur C++ developer, poor IDEs make me favor short names. I'd even like to drop _t, but I won't be demanding it.
Title: Re: German in the code
Post by: kierongreen on September 21, 2013, 03:29:33 PM
simobj to me doesn't mean anything more than obj. When you consider we have simworld, simplayer, simhalt, sim* all over the game what does adding sim as a prefix actually mean?

About IDEs - some people don't use them. I don't for one.

Anyway, regarding context, examples of where ding is used at the moment are:
Code: [Select]
gr->obj_bei(0)->get_typ()==ding_t::baum

const ding_t *dt = gr->obj_bei(i);

ding_t::typ typ = (ding_t::typ)file->rd_obj_id();

case ding_t::old_automobil:
case ding_t::automobil: v = new automobil_t(welt, file, first, last);  break;
case ding_t::old_waggon:
case ding_t::waggon:    v = new waggon_t(welt, file, first, last);     break;
case ding_t::old_schiff:
case ding_t::schiff:    v = new schiff_t(welt, file, first, last);     break;
case ding_t::old_aircraft:
case ding_t::aircraft:    v = new aircraft_t(welt, file, first, last);     break;
case ding_t::old_monorailwaggon:
case ding_t::monorailwaggon:    v = new monorail_waggon_t(welt, file, first, last);     break;
case ding_t::maglevwaggon:         v = new maglev_waggon_t(welt, file, first, last);     break;
case ding_t::narrowgaugewaggon:    v = new narrowgauge_waggon_t(welt, file, first, last);     break;

In each case ding does not provide the context at the moment, other variable names or types around do. So obj would just be the same, only it's slightly shorter, and much shorter than some other suggestions which could really bulk out some sections of code making them less easy to read.
Title: Re: German in the code
Post by: Markohs on September 21, 2013, 04:09:34 PM
I'm surprised you don't see any difference between obj_t and simobj_t. to me it's clear the first one is a generic object with no special traits and the second it's a object related to the simulation. obj_t it's the name you' d use when implementin let's say a list of generic objects.
Following tour reasoning we might use as well o_t or simply o.
You choose not using an IDE. I respect that,  but I don't think that means we need to change our guidelines to make it easier for people to write code like that. after all we are talking about a big project, not a complete toy project. We are being all reasonable too,  and proposing short enough alternate names..
Title: Re: German in the code
Post by: Ters on September 21, 2013, 05:49:42 PM
simobj to me doesn't mean anything more than obj. When you consider we have simworld, simplayer, simhalt, sim* all over the game what does adding sim as a prefix actually mean?

Those are names of files, not names of classes. And it's the files that has a meaningless prefix. Ideally, those files should be renamed to match the classes in them. I still get confused when looking for something, because the file has a sim prefix that I didn't think about.
Title: Re: German in the code
Post by: sdog on September 21, 2013, 06:32:30 PM
Ok, i see, i would not have thought one would want to change a global variable.

Side effects of functions are something i deeply dislike. It is one of the main reasons i still don't understand the code i'm working with for 5+ years.

The globals i used before are all non-mutable. They are the parameters i give to a program. But it would be unwieldly to pass a dozen of integers and reals to a function.
(In Haskell i could easily do this by passing tuples [those are structs in C?])


Quote
if you are a disciplined programmer you know the function you have in front of your eyes only modifies variables you have in front of your eyes.
Can't you just set the function to 'pure'? Or are there no provisions for that in C?

fortrans way would be: PURE SUBROUTINE ...
... when this piece of obsolete junk has it, C++ like does as well?

Quote
Sorry for the long post, I hope I didn't bore you.
No, not at all. Thank you Markohs very much for taking the time to explain this well and in detail. It is very clear now to me why global variables are to be avoided.


Quote
Prissi: This is in fact not restricted only to globals, but all mutable objects shared between the threads.
Globals are exacerbating the problem already present. But this reminds me of something, it isn't enough a global mutable variable's state is never changed, the complier needs to know it also. Is there a way for the compiler to determine a variable is only changed at the start of a program when reading data. Or would it have to be declared as a constant (but then it would need to be known at compile time, not just at one point in runtime). (not a serious question i ask in hope of an answer, as such an answer would be highly language specific, and i wouldn't use C++ anyway)
Title: Re: German in the code
Post by: Ters on September 21, 2013, 06:49:38 PM
Ok, i see, i would not have thought one would want to change a global variable.

Side effects of functions are something i deeply dislike. It is one of the main reasons i still don't understand the code i'm working with for 5+ years.

The globals i used before are all non-mutable.

That would be a global constant, which I have never understood to be a problem.

fortrans way would be: PURE SUBROUTINE ...
... when this piece of obsolete junk has it, C++ like does as well?

C++ inherits much of its rules from C, and C is ancient. The mindset of C is also very different from Fortran. Fortran has a higher level of abstraction. C on the other hand, is almost nothing more than glorified assembly, and lets you do anything (although screwing up the call stack requires climbing or falling into some implementation specific trap doors that aren't really part of the language).
Title: Re: German in the code
Post by: Markohs on September 21, 2013, 07:01:12 PM
That would be a global constant, which I have never understood to be a problem.

 Ofc they are not a problem, defining and using constants that you will use around the code it's good design.

 What's nto desired is using literals inside the function, for example set_width(200),  if that code is to be constant, better define a constant like DESIRED_WIDTH=200 and put it on the top of the file,with the rest of constants, or try to centralize all the constants in a single file, or a reduced number of files. :)

 I guess by pure function you refer to this:

http://en.wikipedia.org/wiki/Pure_function (http://en.wikipedia.org/wiki/Pure_function)

 It's not exactly the same concept, but it's similar. It's restrcting the scope of variables it can depend a bit less than a pure function, to just the parameters *AND* the class member variables. But nothing outside the class should affect it's behavior.
Title: Re: German in the code
Post by: prissi on September 21, 2013, 08:47:39 PM
As such any function (which is not const) on an object can never be a pure function. Imho saying globals are bad, but then having object local variables in singletons is the same as using global. Only in a more complicated way.
Title: Re: German in the code
Post by: sdog on September 21, 2013, 09:33:48 PM
Quote
That would be a global constant, which I have never understood to be a problem.
But then it'd have to be set at compile time, not passed as parameter at program start.
Title: Re: German in the code
Post by: Ters on September 21, 2013, 10:33:00 PM
But then it'd have to be set at compile time, not passed as parameter at program start.

In C/C++ atleast, parameters passed to the program at runtime would have to be parsed from the command line and into a variable. At this point, global constants have long since been locked to their values. In C++ and later versions of C, one can create constants later in the program flow, but such constants are scoped to the function creating them, so no other function can know about them or their value. The value itself must be passed explicitly as a parameter to all functions that need to know the value, though any intermediate function as well. (C++ has a concept called functors/function objects, which behaves somewhat differently, but I won't try to explain that now.)
Title: Re: German in the code
Post by: isidoro on September 22, 2013, 12:44:58 AM
Another problem with globals, even if constant, is that your global namespace gets dirty.  You never know if some name is already taken somewhere else.  Moreover, the global name can be obscured by a local variable with the same name and that can get unnoticed, with undesired side-effects, or two different people on the same project can choose the same name for different purposes in their branches, or...  And that problem is shared with global functions.

[...]
I think you guys would completely hate programming java. :)

I do!  I don't understand people that like it so much.  Not to mention Fortran.  It was a real pain when I had to work with that "language".

[...]
About IDEs - some people don't use them. I don't for one.
[..]

With me, we are two...   ;)   I find them too uncomfortable to use.  And pretty slow.  And you lose half an hour to find easy things, hidden in menus, like where to set command line arguments in Visual Studio.

Some of the thoughts I have seen in this thread are just a matter of personal choice (some are just false: Fortran is 20 years older than C, for instance), even if they are quite widespread.

My advice is that you choose the options that make programming more comfortable for the majority of developers.  Some people like to wear ties, some other think that wearing ties is a must, but if you feel more comfortable wearing just a t-shirt, do it!
Title: Re: German in the code
Post by: Ters on September 22, 2013, 08:10:57 AM
I do!  I don't understand people that like it so much.
[...]
With me, we are two...   ;)   I find them too uncomfortable to use.  And pretty slow.  And you lose half an hour to find easy things, hidden in menus, like where to set command line arguments in Visual Studio.

The key to liking Java for me was IDEs. After learning a handful of hotkeys, less than I've seen some people use in Simutrans, they write much (but not most) of the code for me. The ease of which one can start using a library in a project is also miles apart from C/C++, or pretty much any language I know of, except those languages that also run on the Java platform. (Although I suspect this leads to more breeches of open source licenses than would otherwise be the case.)

So the strength of Java isn't so much the language in itself (although I guess the lack of a preprocessor makes it easier for IDEs to understand the code), but the ecosystem around it. Some have found the Java language itself less than ideal, and have made other languages that run on the Java plaform and therefore can take advantage of the established ecosystem.
Title: Re: German in the code
Post by: TurfIt on September 22, 2013, 04:27:24 PM
Can we *STOP* with these piecemeal translations...
If you're so hellbent on this useless endeavour - do it all at once. Completely. Then never again.
Completely - WTF does 'dt' stand for in 'obj_t *dt =' ?      'ding_t *dt = ' - atleast made sense...
Best guess it'll now take me 8 hours of wasted time to merge in what I've been working on. And once done, just in time for another commit completely breaking things again; All for absolutely no gain, no new features added, no bugs fixed. Nothing. I'd rather spend my time working on something useful, this isn't it.
Title: Re: German in the code
Post by: kierongreen on September 22, 2013, 04:38:31 PM
I thought we'd decided now was the time for translating? No?
Title: Re: German in the code
Post by: Ters on September 22, 2013, 04:44:45 PM
There is a gain. A huge fraction of the Earth developers won't have to run the code through Google translate (or flip through a dictionary) to understand the Simutrans source code. But I agree that translations should be applied to trunk in as few commits as possible, at points where all other major projects has a chance to be prepared for it and don't have lots of work ready for committing. We can't save stale patches that are just lying around, they're likely broken by the big changes done to karte_t and the GUI anyway, but at least give the active projects time to synchronize.

(Reminds me of a day at work a few weeks ago, where one of my colleagues spent half a day trying to commit, but every time he managed to merge the latest changes on trunk into the code he was about to submit, someone else had committed a new changelist which necessitated a new merge operation.)
Title: Re: German in the code
Post by: kierongreen on September 22, 2013, 05:06:31 PM
My thoughts were to get the BIG translations (ding to obj, besch to desc) out the way quickly as these affect most files in the game. Smaller ones such as bruecke to bridge while still involving lots of code lines are at least limited to a smaller number of files.
Title: Re: German in the code
Post by: Ters on September 22, 2013, 05:25:55 PM
My thoughts were to get the BIG translations (ding to obj, besch to desc) out the way quickly as these affect most files in the game. Smaller ones such as bruecke to bridge while still involving lots of code lines are at least limited to a smaller number of files.

That's a good plan, but not so quickly that others can't prepare for it. Especially as central developers as TurfIt.
Title: Re: German in the code
Post by: Markohs on September 22, 2013, 06:31:41 PM
Wait, Turfit, I have one last change coming, environment->env, as was required by prissi.

Commiting it soon, and no more changes from me.

EDIT: I see prissi already changed it, so never mind. The file was not renamed, but well, let's let this stay as it is.
Title: Re: German in the code
Post by: kierongreen on September 22, 2013, 06:33:37 PM
Environment to env has already been changed!
Title: Re: German in the code
Post by: Markohs on September 22, 2013, 06:37:47 PM
yes, I saw now, I was just about to change it myself now. ;)

No changes from me then.
Title: Re: German in the code
Post by: kierongreen on September 22, 2013, 06:50:57 PM
I'm tracking down all ding (also dt, d etc) variables renaming them to obj (or similar e.g. new_obj).
Title: Re: German in the code
Post by: prissi on September 22, 2013, 08:30:35 PM
Originally those changes should be done directly after a release. I ratehr would not like them now, as TrufIt wrote. But then, now we are anyway very far from a release ...
Title: Re: German in the code
Post by: An_dz on October 15, 2013, 01:31:03 PM
I did not followed the comments discussion. But I made some changes in dataobj folder.

Edit:
Patches for bauer, display and ifc folder.
Title: Re: German in the code
Post by: kierongreen on October 17, 2013, 08:11:08 PM
Many thanks committed dataobj.diff, bauer.diff, display.diff and ifc.diff to trunk revision 6825.
Title: Re: German in the code
Post by: An_dz on October 17, 2013, 11:53:01 PM
Then here are patches for everything but gui and besch
Title: Re: German in the code
Post by: kierongreen on October 17, 2013, 11:57:03 PM
Eeek that's quite a lot might take a while to look through those! :)

Ok a few comments, there's quite a few examples in these patches of hyphenation being added to words perhaps unnecessarily. For example reestablish to re-establish, reentrant to re-entrant, reseted to re-setted (which could actually just be reset). I also note that it's not just in your patches for example there's exisiting comments such as un-reserve in the code already.

Now in the lot of patches I just committed I just put these hyphenations in since they mostly seemed to be fairly unusual words where I could see it might help people understand the meaning. I'd like some opinions, particularly from non-native speakers of English as to what they find clearest.
Title: Re: German in the code
Post by: Ters on October 18, 2013, 04:53:56 AM
Like Germans, I'm used to bunching words together into infinitely long strings of letters. The only difference is that the original words tend to be shorter than the German equivalent. So I'm used to reading without hyphens or (an abundance of) spaces.
Title: Re: German in the code
Post by: An_dz on November 25, 2013, 07:51:35 PM
A patch to fix all typos you guys made from r6864 to r6922.
Title: Re: German in the code
Post by: IgorEliezer on November 26, 2013, 07:33:08 AM
A patch to fix all typos you guys made from r6864 to r6922.
I see what you did there! :E
Title: Re: German in the code
Post by: An_dz on December 09, 2013, 01:11:57 AM
Two patches to fix some typos.

One for history and simuconf.tab, and another for new typos brought between r6969 and r6972, it's only on grund_besch.cc and brueckenbauer.cc.
I also included a comment on brueckenbauer.cc to explain one error message.

And have anyone finished reviewing the last one? (r6864-r6922)
Title: Re: German in the code
Post by: jamespetts on November 15, 2016, 01:13:08 AM
Apologies for necroposting, but I thought that it might in this instance be preferable to starting a new thread on the same topic.

I wonder whether it might be time to make more progress on this project? There are still quite a lot of untranslated variable/class/function/file names in Simutrans, and this may well be putting off new contributors. Indeed, a prospective contributor to Simutrans-Experimental has recently described the large amount of German in the code as "daunting", although he tells me that, happily, he still intends to work on the project.

I really do not want to have different variable/class names in Standard than Experimental, however, as it would make merging much harder, and I do not think it helpful to developers of either if the code-bases drift apart in non-functional ways. If I were to set myself up to compile Standard and produce some more translation patches, would there be a good chance of these being accepted?

Some of the names that I consider are in a high priority to translate are (with suggested alternatives in brackets following):
  • convoi (convoy)
  • besch (base_type)
  • grund (ground
  • bild (image - this has already been translated in some places, but remains in others)
  • eintrag (entry)
  • fahrplan (shcedule - only the filenames need renaming, I think)
  • fussgaenger_besch_t (pedestrian_base_type_t)
  • gebaeude (building)
  • stadt (city)
  • fabrik (industry)
  • fundament (foundation)
  • planquadrat (ground_tile)
  • platzsucher (location_finder)
  • simfab (simindustry)
  • ware (cargo)
  • warenzeil (cargo_destination)
  • wasser (water)
  • zeiger (pointer)
  • raucher (smoke_producer)
  • vehikel (vehicle)
  • bauer (builder)
  • boden (ground)
  • linien (line)
  • eintrag (entry)
  • schiene (railway)
  • strasse (road)
  • bauigel (constructor)
  • route_fuer (route_for)
  • ist_doppel (is_double)
  • ribi (direction_bits - I know that this is longer, but it makes what this is about so much clearer)
  • ist_einfach (is simple)
  • ist_wegbar (is_pathable)
  • ow (ew)
  • ost (east)
  • nord (north)
  • sued (south)
  • laden (load)
  • alle (all)
  • doppelr (double)
  • rueckwaerts (backwards)
  • exakt_orthogonal (exact_orthagonal)
  • ist_ (is_)
  • einfach (simple)
  • kurve (curve)
  • gerade (just)
  • hang (slope)
  • optionen (options)
  • kennfarbe (colour)
  • farbengui_t (colour_gui_t)
  • haus (structure - this cannot also be "building")
  • kanal (canal)
  • karte (map)
  • liefere_an (suppy)
  • starte_mit_route (start_with_route)
  • hole_ab (unload)
  • get_ware_fuer_zielpos (get_cargo_for_destination_pos)
  • get_ware_summe (get_cargo_amount)
  • liefere_an_fabrik (deliver_to_factory)
  • sortierung (sorting)
  • welt (world)
  • koord (coord)
  • haltestellen (stops)
  • haltestelle (stop)
  • verbrauch (consumption)
  • anzahl (number)
  • kapazitaet (capacity)
  • platzierung (placement)
  • produktivitaet (productivity)
  • bereich (range)
  • gewichtung (chance)
  • lieferanten (suppliers)
  • produkte (products)
  • rauch (smoke)
  • fab (ind)
  • verteile (distribution)
  • ausgang (exit)
  • eingang (entry)
  • vorrat_an (stockpile)
  • fpl (sch)
  • baue (build)
  • hierarchie (chain)
  • zufallsbauplatz (random_building)
  • finde (find)
  • sucher (search)
  • hersteller (producer)
  • bauplatz (place_to_build)
  • spezial (special)
  • bau (build)
  • bewerte (check_value - I am not sure about this translation)
  • wachstum (growth
  • zufallspunkt (random_point)
  • arbeiterziel (workplace)
  • senke (sink)
  • pumpe (source)
  • linksoben (top_left)
  • rechtsunten (bottom_right)
  • lo (tl)
  • ur (br)
  • bruecke (bridge)
  • baum (tree)
Despite the length of the list, I have probably missed quite a few. As far as I can see, all of these can be refactored with a simple search/replace (provided that all superset strings are searched/replaced before all of their subsets).

Would a patch containing such replacements (or multiple patches containing fragments of them at a time) be acceptable? Would anyone like to propose a better translation for any of my suggestions above?

The next project after that would be translating the remaining code comments, but the class/file/variable/function names seem more important.
Title: Re: German in the code
Post by: TurfIt on November 15, 2016, 01:20:54 AM
convoi != convoy.
Title: Re: German in the code
Post by: jamespetts on November 15, 2016, 02:18:07 AM
What is the difference?
Title: Re: German in the code
Post by: Ters on November 15, 2016, 06:24:53 AM
What is the difference?

Everything, except that they have to do with transportation. The convoi used in Simutrans is also apparently not a German word, but a French. The German word for convoy is Konvoi. And even the French word is apparently incorrectly used. (Although the phrase "convoi exceptionnel" seems a special case that would fit, but that special case does not exist in Simutrans either.)

There are no convoys in Simutrans! The closest you get is a congestion.
Title: Re: German in the code
Post by: jamespetts on November 15, 2016, 11:18:49 AM
Perhaps, then, "assemblage"?
Title: Re: German in the code
Post by: DrSuperGood on November 15, 2016, 02:36:27 PM
Quote
convoi != convoy.
I always thought it represented "convoy" because the object consists of a whole lot of individual transport units following each other like a convoy.

Maybe suggest an alternative? The type names should be clear English and not made up or borrowed from other language words.

Quote
simfab (simindustry)
I thought it was short for sim fabrik which should be "simfactory". Although I guess industry is also a valid alternative.
Title: Re: German in the code
Post by: An_dz on November 15, 2016, 03:32:06 PM
The type names should be clear English and not made up or borrowed from other language words.
Is that not the definition of language? :D ;) Even more with English.
Title: Re: German in the code
Post by: jamespetts on November 15, 2016, 07:10:51 PM
Other than the issue with "convoy", is everyone happy with the suggested search/replace alternatives suggested above? If "convoi" were to go to "assemblage", all "cnv" local variables would have to change to "****" or similar.
Title: Re: German in the code
Post by: Tjoeker on November 15, 2016, 08:48:56 PM
But isn't a convoy in English a set of vehicles bound together?

Edit:
See, if I look up convoy in google I get this:
(https://www.filmlinc.org/wp-content/uploads/2016/03/convoy-1600x900-c-default.jpg)

Title: Re: German in the code
Post by: Ters on November 15, 2016, 09:38:53 PM
Some of these words are hard to translate out of context. I would expect "gerade" to mean "straight". "schiene" is probably "track" as in "railway track", rather than "railway", which I imagine to be more broader in scope. "pathable" seems like a very artificial word to me. I think "sucher" is "searcher", rather than "search", but "finder" might be a more established term in software development. Isn't "building site", or "construction site", a more natural term than "place to build"? "Calculate value" seems a more correct translation of "bewerte" in general than "check value".
Title: Re: German in the code
Post by: Vladki on November 15, 2016, 09:44:42 PM
I think that convoy is the right translation of Konvoi or convoi. The problem is that the term is used differently in simutrans than in real world. In simutrans it is used to mean train, or its equivalent for road or water transport. So "train" could be as well used as translation, but I think that most developers and also player are already used to the modified meaning of convoy in simutrans.
Title: Re: German in the code
Post by: prissi on November 15, 2016, 09:57:20 PM
Quote
convoi (consist)
besch (desc) from description or (prop) from properties
...
planquadrat (tile)
...
ware (cargo) well passengers, mail and nothign are hardly cargo ... but for a lack of better word ...
...
zeiger (indicator) pointer usually means something else in computer-lingo ...
raucher (smoker)
...
boden (soil) You cannot have to thing which are "ground"
...
schiene (track) as this type is the foundation for any track-based transport
,,
bauigel (constructor)
...
ist_doppel (is_twoway)
ribi is not a german word, so I would keep it anyway ...
ist_einfach (is_oneway)
ist_wegbar (is_driveable)
...
laden (loading)
...
doppelr (double_ribi)
rueckwaerts (get_backwards)
exakt_orthogonal (exact_orthagonal)
ist_ (is_)
einfach (simple)
kurve (bend)
gerade (straight)
hang (slope does not work, there is a slope type already
optionen (option_frame_t)
kennfarbe (industry_color) do not find it elsewhere
farbengui_t (colour_gui_t)
haus (building_structure - this cannot also be "building")
kanal (waterway)
karte (map) not possible, map is used too
liefere_an (suppy_to)
starte_mit_route (start_with_route)
hole_ab (load_from) (but depends on context)
...
sortierung (sort)
welt (world) is mostly done already
koord (coord) has been done too
haltestellen (stop_list)
...
ausgang (outgoing)
eingang (incoming)
...
fpl (sched)
...
bewerte (rank)
...
senke (drain)
pumpe (source) (but I think they are already converted)
...

Quite some suggestions have been done already.
Title: Re: German in the code
Post by: Ters on November 15, 2016, 10:14:40 PM
"sink" is probably a more common term than "drain" in the context of simulation.
Title: Re: German in the code
Post by: Vladki on November 15, 2016, 10:17:47 PM
Quote
ist_doppel (is_twoway)
ribi is not a german word, so I would keep it anyway ...
ist_einfach (is_oneway)
ist_wegbar (is_driveable)

Have a look at dataobj/ribi.h and class hang_t:
// wegbar: flat enough for ways, infach=only one ew/ns direction, doppel=two height difference
Title: Re: German in the code
Post by: isidoro on November 15, 2016, 11:26:37 PM
I think that some of the word are more urgent that others.  It doesn't matter whether you write convoi, konvoi, convoy, assemblage, etc., an English speaker can easily guess the meaning.  I would leave it like it is, with its short form (cnv).

Just the opposite with wachstum (growth), anzahl (number), baum (tree), to name only a few.  Those are really the most urgent to translate.  If you are German, Nordic, or even English, maybe you find those German terms familiar, but for non northern language speakers, they are a total mystery when reading the code.
Title: Re: German in the code
Post by: jamespetts on November 15, 2016, 11:47:02 PM
Thank you for all the feedback. It would be good to unify the language of variables/functions/classes/files once and for all. Prissi - thank you for copying that list, and apologies for not having noticed it. Do I understand that you are content with all of the terms set out in it, or would you propose any modifications to it? The next step would seem to me to be to produce a combined list with the best of the original suggestions and my suggestions and try to get consensus (within reason) as to the optimum replacement word in each case. The sooner that we get this done, I think, the sooner that we will have an increased likelihood of new developers working on the code in both Standard and Experimental, which will benefit the whole community.

Edit: Another translation that we probably need and should be easy: get_zeit_ms should become get_ticks.
Title: Re: German in the code
Post by: Ters on November 16, 2016, 06:32:22 AM
Edit: Another translation that we probably need and should be easy: get_zeit_ms should become get_ticks.

In my experience, ticks and milliseconds are not usually the same. "get_time_ms" would be a better translation, assuming the get_zeit_ms function does what I think it does; I don't have any context for it.
Title: Re: German in the code
Post by: Tjoeker on November 16, 2016, 07:31:16 AM
as far as I know, get_zeit_ms gives you the number of ticks that passed by since the new month started.
So get_ticks seems good to me.
However, get_time might explain a bit easier what it does?
Title: Re: German in the code
Post by: jamespetts on November 16, 2016, 07:40:44 AM
The actual function just returns the value of a variable called "ticks", so get_ticks would follow the normal convention.
Title: Re: German in the code
Post by: DrSuperGood on November 16, 2016, 02:38:51 PM
Many of the method comments need to be rewritten, or even written to start with. Some of them are not very helpful as to explaining the purpose or functionality of a method.
Title: Re: German in the code
Post by: jamespetts on November 16, 2016, 02:54:40 PM
The comments can perhaps wait until the more urgent re-naming task is done. Comments may be better written by those with a more intimate knowledge of the whole code than I.
Title: Re: German in the code
Post by: Ters on November 16, 2016, 05:24:08 PM
as far as I know, get_zeit_ms gives you the number of ticks that passed by since the new month started.
So get_ticks seems good to me.
However, get_time might explain a bit easier what it does?

The actual function just returns the value of a variable called "ticks", so get_ticks would follow the normal convention.

That just shows how wrong things can get if one considers names without the context, like with just the massive lists. I tried to find get_zeit_ms, but couldn't find it.
Title: Re: German in the code
Post by: jamespetts on November 16, 2016, 09:37:31 PM
Is this one whose name has changed in Standard and not caught up in Experimental, or have I got the e and the i the wrong way around again?

Edit: We also need, I think:

  • vorgaenger (leader); and
  • nachfolger (follower).
Title: Re: German in the code
Post by: Dwachs on November 17, 2016, 01:09:31 PM
This is still there in simworld.h
Code: [Select]
uint32 get_zeit_ms() const { return ticks; }
Title: Re: German in the code
Post by: jamespetts on November 17, 2016, 01:23:51 PM
Yes, that was what I was referring to.
Title: Re: German in the code
Post by: Ters on November 17, 2016, 03:39:58 PM
This is still there in simworld.h
Code: [Select]
uint32 get_zeit_ms() const { return ticks; }

I was looking in various simsys files and then simmain, because that was where I expected a function returning the time in milliseconds to be. It was only later revealed that the name was misleading.
Title: Re: German in the code
Post by: prissi on November 17, 2016, 10:26:53 PM
Also leader and follower is not very good translation. Rather "leading" and "trailing" seems better, as it describe a function (which is the purpose of verbs).
Title: Re: German in the code
Post by: Dwachs on November 18, 2016, 08:44:13 PM
Here is a translation of ribi.h . Please check if this is understandable. What is the correct expression for 'non-straight way'? bend? curve? What would be the corresponding bool function: is_curve(d) / is_bend(t) ?
Title: Re: German in the code
Post by: Vladki on November 18, 2016, 10:24:48 PM
I would prefer bend. But that's just because curve sounds too close to one (not only) czech insult ;)
Title: Re: German in the code
Post by: Ters on November 18, 2016, 10:32:56 PM
Also leader and follower is not very good translation. Rather "leading" and "trailing" seems better, as it describe a function (which is the purpose of verbs).

But are verbs the right to use here? It seems natural to me that types and variables are nouns (or sometimes noun phrases), while functions are verbs or (perhaps some would say unfortunately) more commonly verb phrases, both in the imperative mood. "Leading" and "trailing" can also be seen as verbal adjectives, though, and adjectives are common in enums or similar constants.

The comments always use the full term "leading vehicle" and "trailing vehicle", except in case which uses "trailer". But I'm not so certain these terms are quite correct, especially the first one. When I hear or read "leading vehicle", I think of the foremost vehicle, but that is not the case here. Perhaps "preceeding vehicle" is better? If using an IDE with good auto-completion, especially one that understands initials, I would not hesitate to use more than one word for this. In my Pak Explorer, I've called these fields "numPossibleBefore" and "numPossibleAfter".
Title: Re: German in the code
Post by: isidoro on November 18, 2016, 11:52:56 PM
Here is a translation of ribi.h . Please check if this is understandable. What is the correct expression for 'non-straight way'? bend? curve? What would be the corresponding bool function: is_curve(d) / is_bend(t) ?

Good for me, except for line 209:
Quote
Code: [Select]
   static ribi rueckwaerts(ribi x) { return rwr[x]; }

Another question: why not change defines in lines 44-47 and lines 111-114 so that if corner1 is swcorner it's named like that?
Quote
Code: [Select]
#define sw_corner(i) (i%3)        // sw corner
#define se_corner(i) ((i/3)%3)    // se corner
#define ne_corner(i) ((i/9)%3)    // ne corner
#define nw_corner(i) (i/27)       // nw corner

I don't know which would be better, curve or bend.
Title: Re: German in the code
Post by: jamespetts on November 19, 2016, 12:34:19 AM
Briefly: I think that Prissi is correct about leading/trailing, and that Isidoro's suggestion to use "corner" in the manner that he suggests is sensible.
Title: Re: German in the code
Post by: kierongreen on November 19, 2016, 10:44:16 AM
In English generally roads have bends (or corners if particularly sharp), and railways have curves. Though they can be used interchangeably so take your pick!
Title: Re: German in the code
Post by: Dwachs on November 19, 2016, 04:53:14 PM
Committed the ribi translation with r7947. Translated also north/south/east and related directions.

I added some bash script files for doing these automatically in translate_code/. Call the script like this
Code: [Select]
./batch_replace translate_nsew.csv
the parameter is a comma-separated list of translations: original,translated.

The next step would be to translate the files in grund/. Here I have some questions regarding translation:
  • grund_t -> tile_t - this is the base class. I would prefer a short name.
  • boden_t -> soil_t ? These are tiles that  contain ways, trees, no buildings. How to call them?
  • halt -> stop ?? I do not like this. But it seems to be the correct English word?
  • karten_boden -> ground or surface? These are the tiles at the surface of the earth.
  • natur -> empty
  • planquadrat -> grid_square or map_square?
  • wasser -> water or sea?
  • *_nr -> *_no  There are many member variables that store an index (image number etc). What would be correct abbreviation? bild_nr -> image_no?

Edit: renamed fahrplan.* -> schedule.*, linieneintrag.h -> schedule_entry.h
Title: Re: German in the code
Post by: kierongreen on November 19, 2016, 08:53:42 PM
In my opinion nr works as an abbreviation for number I wouldn't see a need to change it. wasser to water and grund to ground make sense to me. halt could stay as is. boden I would say could become tile. karten_boden could become landscape? natur to empty seems good, planquadrat to grid_square seems better option I think.
Title: Re: German in the code
Post by: Vladki on November 19, 2016, 09:01:01 PM
grid_square and tile seem a synonym to me (for planquadrat). I think boden should be translated as base, bootom, land, terrain or such
Title: Re: German in the code
Post by: prissi on November 19, 2016, 09:02:54 PM
Tile is rather the planquadrat_t or grund_t ... (map_square_t or mabe really grid_square_t could be another take at planquadrat).

I would rather see grund_t is a general tile_t and boden_t becomes ground_t. THen kartenboden could become map_ground_t ...

Title: Re: German in the code
Post by: Dwachs on November 19, 2016, 09:31:11 PM
what about
  • grund_t -> tile_t (base type, short name)
  • boden_t -> ground_t (some tile with green gras)
  • karten_boden -> surface (after all, these are the tiles precisely at the surface)
  • planquadrat -> grid_square
@Vladki: planquadrat is the class that holds a list/stack of all tiles at the same (x,y) position

Next question, much more difficult ;)  How to translate *_besch_t ?  The more I think about it, the more I like *_type_t. building_type_t etc looks good. Other proposals were: desc (descriptor - I used this for the squirrel interface), and prop (for properties).
Title: Re: German in the code
Post by: jamespetts on November 19, 2016, 11:37:19 PM
All splendid ideas. As to *_besch_t, I am not a fan of *_type_t as the trailing "t" also stands for "type", so there is an element of redundancy. "Base", perhaps?
Title: Re: German in the code
Post by: DrSuperGood on November 20, 2016, 05:07:07 AM
Quote
All splendid ideas. As to *_besch_t, I am not a fan of *_type_t as the trailing "t" also stands for "type", so there is an element of redundancy. "Base", perhaps?
The _t suffix represents a type name, as opposed to a variable or other sort of name, with regard to programming in C/C++. Hence type_t is not redundant as it is a C/C++ type called type. Type ultimately best describes what the object is.

In games like StarCraft II all data is managed using XML databases. There each type of data is described as a scope with instances of a scope being referred to as entries. If such a naming approach was adopted it would make it *_scope_t. If this is more readable/sensible than *_type_t is questionable.

Title: Re: German in the code
Post by: Ters on November 20, 2016, 09:25:57 AM
I lean towards desc over type, because not all of these things are strictly speaking types (beyond what the _t suffix represents). A type is usually made up be several such nodes, and a few skins don't really represent any kind of type at all. That desc has been used in parts of the code also gives some precedent. The directory containing them should called descriptors, to make the meaning clear.
Title: Re: German in the code
Post by: jamespetts on November 20, 2016, 10:26:30 AM
The idea of using an unabbreviated directory name to make the abbreviated type names clear is a good one.
Title: Re: German in the code
Post by: prissi on November 20, 2016, 09:42:06 PM
Also some objects already have a type (which is a uint8), so another get_type() returning a former besch * will add confusion ...
Title: Re: German in the code
Post by: DrSuperGood on November 21, 2016, 06:00:41 AM
Quote
Also some objects already have a type (which is a uint8), so another get_type() returning a former besch * will add confusion ...
That method should be refactored into something more meaningful such as get_classification(). The return value is an abstract indicator as to the object type, a classification for the object, without needing to know the details of the object type. Sure it is slightly longer, but also more meaningful.

In theory besch type objects can be considered to represent an entry in a database of sorts. They also represent available types.  Hence it might have more meaning to label them so.
object_type_entry_t
factory_type_entry_t
way_object_type_entry_t
etc...
Unfortunately this does result in quite long type names. However there should be no ambiguity. The accessor method would then be get_type_entry().
Title: Re: German in the code
Post by: prissi on November 21, 2016, 04:10:27 PM
The besch are structured data. I fail to see them as entry in database. Also, the names should be probably shorter since they are used a lot.

And desc could also mean descriptor (how to arrange the data), if you are really into database stuff.

EDIT: removed typo and explicit references for clarity
Title: Re: German in the code
Post by: Dwachs on November 25, 2016, 01:17:37 PM
I made some progress replacing 'bild' by image in the code. Here, I did translate the bild-besch classes as:
Code: [Select]
bild_besch_t -> image_t
bildliste_besch_t -> image_list_t
bildliste2d_besch_t -> image_array_t
As these data structures contain just images, I found 'image_t' more appropriate (without any desc/type suffix). What do you think?
Title: Re: German in the code
Post by: Ters on November 25, 2016, 04:03:13 PM
I can certainly think of arguments against such naming, but I'm not sure if I would agree with them myself.
Title: Re: German in the code
Post by: DrSuperGood on November 25, 2016, 09:04:40 PM
Quote
The are mostly structured data.
What does this even mean?

Quote
What do you think?
A possible confusion is with various image APIs such as in Java. They include more context such as colour model of the image to allow better general purpose interoperability.
Title: Re: German in the code
Post by: jamespetts on November 26, 2016, 01:22:32 AM
It is excellent to see some progress on this. I have now set myself up to compile Standard so that I can produce some patches to progress this project further.

Based on discussions so far, may I therefore suggest the following revised version of my original list? Dwachs' idea of having grund_t become type_t and boden_t become ground_t will not work, as there is already a tile_t (a struct defined in simhalt.h).

  • get_zeit_ms (get_ticks)
  • vorgaenger (leading)
  • nachfolger (trailing)
  • convoi (consist)
  • convoihandle (consist_handle)
  • fussgaenger_besch_t (pedestrian_base_type_t)
  • besch (base_type)
  • grund (ground)
  • bild (image - this has already been translated in some places, but remains in others)
  • eintrag (entry)
  • fahrplan (schedule - only the filenames need renaming, I think)
  • gebaeude (building)
  • stadt (city)
  • fabrik (industry)
  • fundament (foundation)
  • planquadrat (grid_square)
  • platzsucher (location_finder)
  • simfab (simindustry)
  • warenzeil (cargo_destination)
  • wasser (water)
  • zeiger (pointer)
  • raucher (smoke_producer)
  • vehikel (vehicle)
  • bauer (builder)
  • boden (soil)
  • linien (line)
  • eintrag (entry)
  • schiene (railway)
  • strasse (road)
  • bauigel (constructor)
  • route_fuer (route_for)
  • ribi (direction_bits - I know that this is longer, but it makes what this is about so much clearer))
  • ow (ew)
  • laden (load)
  • doppelr (double)
  • ist_ (is_)
  • gerade (just)
  • hang (slope)
  • optionen (options)
  • kennfarbe (colour)
  • farbengui_t (colour_gui_t)
  • haus (structure - this cannot also be "building")
  • kanal (canal)
  • karte (map)
  • liefere_an (supply)
  • starte_mit_route (start_with_route)
  • hole_ab (unload)
  • get_ware_fuer_zielpos (get_cargo_for_destination_pos)
  • get_ware_summe (get_cargo_amount)
  • ware (cargo)
  • liefere_an_fabrik (deliver_to_factory)
  • sortierung (sorting)
  • welt (world)
  • koord (coord)
  • haltestellen (stops)
  • haltestelle (stop)
  • halthandle (stop_handle)
  • halt (stop)
  • verbrauch (consumption)
  • anzahl (number)
  • kapazitaet (capacity)
  • platzierung (placement)
  • produktivitaet (productivity)
  • bereich (range)
  • gewichtung (chance)
  • lieferanten (suppliers)
  • produkte (products)
  • rauch (smoke)
  • fab (ind)
  • verteile (distribution)
  • ausgang (exit)
  • eingang (entry)
  • vorrat_an (stockpile)
  • fpl (sch)
  • baue (build)
  • hierarchie (chain)
  • zufallsbauplatz (random_building)
  • finde (find)
  • sucher (search)
  • hersteller (producer)
  • bauplatz (place_to_build)
  • spezial (special)
  • bau (build)
  • bewerte (check_value - I am not sure about this translation)
  • wachstum (growth)
  • zufallspunkt (random_point)
  • arbeiterziel (workplace)
  • senke (sink)
  • pumpe (source)
  • linksoben (top_left)
  • rechtsunten (bottom_right)
  • lo (tl)
  • ur (br)
  • bruecke (bridge)
  • baum (tree)
  • karten_boden (surface)
  • natur (empty)
This should probably be done in stages. Are we happy for me to start with the following?

  • get_zeit_ms (get_ticks)
  • vorgaenger (leading)
  • nachfolger (trailing)
  • convoi (consist)
  • convoihandle (consist_handle)
  • fussgaenger_besch_t (pedestrian_base_type_t)
Title: Re: German in the code
Post by: Dwachs on November 26, 2016, 07:30:05 AM
tile_t in haltestelle_t can be renamed first to something different.

Also I think this thread came to the agreement to translate besch to desc(riptor).

My idea of developing translation patches was to construct csv files, that contain all the replacement. The purpose of this was to make the process as automatic as possible. In fact, all the translation patches I committed to trunk in the last days were done in this way. The only manual adjustment was to revert some changes to strings like "Nord" which are anyway translated on output.

If you provide any patches, I will be happy to include them.
Title: Re: German in the code
Post by: jamespetts on November 26, 2016, 12:34:34 PM
Thank you for that. Perhaps tile_t can become stop_tile_t, so that we then get this:

  • get_zeit_ms (get_ticks)
  • vorgaenger (leading)
  • nachfolger (trailing)
  • convoi (consist)
  • convoihandle (consist_handle)
  • fussgaenger_besch_t (pedestrian_base_type_t)
  • besch (desc)
  • tile_t (stop_tile_t)
  • grund (tile)
  • gr (tile)
  • boden (ground)
  • bd (gr)
  • bild (image - this has already been translated in some places, but remains in others)
  • eintrag (entry)
  • fahrplan (schedule - only the filenames need renaming, I think)
  • gebaeude (building)
  • stadt (city)
  • fabrik (industry)
  • fundament (foundation)
  • planquadrat (grid_square)
  • platzsucher (location_finder)
  • simfab (simindustry)
  • warenzeil (cargo_destination)
  • wasser (water)
  • zeiger (pointer)
  • raucher (smoke_producer)
  • vehikel (vehicle)
  • bauer (builder)
  • linien (line)
  • eintrag (entry)
  • schiene (railway)
  • strasse (road)
  • bauigel (constructor)
  • route_fuer (route_for)
  • ribi (direction_bits - I know that this is longer, but it makes what this is about so much clearer))
  • ow (ew)
  • laden (load)
  • doppelr (double)
  • ist_ (is_)
  • gerade (just)
  • hang (slope)
  • optionen (options)
  • kennfarbe (colour)
  • farbengui_t (colour_gui_t)
  • haus (structure - this cannot also be "building")
  • kanal (canal)
  • karte (map)
  • liefere_an (supply)
  • starte_mit_route (start_with_route)
  • hole_ab (unload)
  • get_ware_fuer_zielpos (get_cargo_for_destination_pos)
  • get_ware_summe (get_cargo_amount)
  • ware (cargo)
  • liefere_an_fabrik (deliver_to_factory)
  • sortierung (sorting)
  • welt (world)
  • koord (coord)
  • haltestellen (stops)
  • haltestelle (stop)
  • halthandle (stop_handle)
  • halt (stop)
  • verbrauch (consumption)
  • anzahl (number)
  • kapazitaet (capacity)
  • platzierung (placement)
  • produktivitaet (productivity)
  • bereich (range)
  • gewichtung (chance)
  • lieferanten (suppliers)
  • produkte (products)
  • rauch (smoke)
  • fab (ind)
  • verteile (distribution)
  • ausgang (exit)
  • eingang (entry)
  • vorrat_an (stockpile)
  • fpl (sch)
  • baue (build)
  • hierarchie (chain)
  • zufallsbauplatz (random_building)
  • finde (find)
  • sucher (search)
  • hersteller (producer)
  • bauplatz (place_to_build)
  • spezial (special)
  • bau (build)
  • bewerte (check_value - I am not sure about this translation)
  • wachstum (growth)
  • zufallspunkt (random_point)
  • arbeiterziel (workplace)
  • senke (sink)
  • pumpe (source)
  • linksoben (top_left)
  • rechtsunten (bottom_right)
  • lo (tl)
  • ur (br)
  • bruecke (bridge)
  • baum (tree)
  • karten_boden (surface)
  • natur (empty)
  • verbindung (connexion)
  • position_bei (get_position)
One disadvantage with the cascade is that we have to translate all of the local variables, too, as tile_t* gr does not make much sense.

I am not quite sure how to set up or use the .csv files to which you refer, but I can certainly supply translation patches (to follow).

Edit: I have added a translation for verbindung and position_bei
Title: Re: German in the code
Post by: Dwachs on November 26, 2016, 01:45:04 PM
Please check out the csv files in this directory: https://github.com/aburch/simutrans/tree/master/translate_code

There is a bash script (for a linux terminal) that will do the translation
Code: [Select]
./batch_replace.sh foo.csv
will replace all pairs in the csv file in all source files in the repository. I do not know how this can be done under windows, but maybe you have a shell available under mingw or git.
Title: Re: German in the code
Post by: jamespetts on November 26, 2016, 03:23:44 PM
Thank you for that.

I am working on the first of the patches now, but I am having trouble with the interaction with the Squirrel API (which I have not updated for Experimental, so of which I do not have experience with working). It seems that there are some references to "convoi" buried in the Squirrel API code that is not part of the Visual Studio project and which is not, therefore, switched out with a search/replace.

Having replaced "convoi" with "consist", I get the following error, suggesting that "convoi" lingers somewhere:

Code: [Select]
1>------ Build started: Project: Simutrans, Configuration: Debug Win32 ------
1>C:\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\V140\Microsoft.CppBuild.targets(368,5): warning MSB8004: Output Directory does not end with a trailing slash.  This build instance will add the slash as it is required to allow proper evaluation of the Output Directory.
1>  C:\Users\James\Documents\Development\Simutrans\Sources\trunk\revision.jse(7, 1) WshShell.Exec: The system cannot find the file specified.
1>
1>
1>  simtool.cc
1>c:\users\james\documents\development\simutrans\sources\trunk\gui\components\gui_textinput.h(135): warning C4267: 'return': conversion from 'size_t' to 'scr_coord_val', possible loss of data
1>c:\users\james\documents\development\simutrans\sources\trunk\gui\components/gui_numberinput.h(68): warning C4267: 'argument': conversion from 'size_t' to 'scr_coord_val', possible loss of data
1>simtool.cc(392): warning C4267: 'argument': conversion from 'size_t' to 'uint8', possible loss of data
1>simtool.cc(5355): warning C4244: '=': conversion from 'sint64' to 'sint32', possible loss of data
1>simtool.cc(5423): warning C4244: '=': conversion from 'sint64' to 'sint32', possible loss of data
1>simtool.cc(5518): warning C4244: '=': conversion from 'sint64' to 'sint32', possible loss of data
1>  api_param.cc
1>script\api_param.cc(339): error C2039: 'get': is not a member of 'script_api::param<consist_t *>'
1>  script\api_param.cc(339): note: see declaration of 'script_api::param<consist_t *>'
1>  api_obj_desc.cc
1>  api_consist.cc
1>c:\users\james\documents\development\simutrans\sources\trunk\script\api\../api_function.h(477): error C2039: 'get': is not a member of 'script_api::param<consist_t *>'
1>  c:\users\james\documents\development\simutrans\sources\trunk\script\api\../api_function.h(261): note: see declaration of 'script_api::param<consist_t *>'
1>  c:\users\james\documents\development\simutrans\sources\trunk\script\api\../api_function.h(476): note: while compiling class template member function 'SQInteger script_api::embed_call_t<F>::call_function(HSQUIRRELVM,R (__cdecl *)(A1,A2),bool)'
1>          with
1>          [
1>              F=script_api::call_tool_init (__cdecl *)(consist_t *,const char *),
1>              R=script_api::call_tool_init,
1>              A1=consist_t *,
1>              A2=const char *
1>          ]
1>  c:\users\james\documents\development\simutrans\sources\trunk\script\api\../api_function.h(193): note: see reference to function template instantiation 'SQInteger script_api::embed_call_t<F>::call_function(HSQUIRRELVM,R (__cdecl *)(A1,A2),bool)' being compiled
1>          with
1>          [
1>              F=script_api::call_tool_init (__cdecl *)(consist_t *,const char *),
1>              R=script_api::call_tool_init,
1>              A1=consist_t *,
1>              A2=const char *
1>          ]
1>  c:\users\james\documents\development\simutrans\sources\trunk\script\api\../api_function.h(271): note: see reference to class template instantiation 'script_api::embed_call_t<F>' being compiled
1>          with
1>          [
1>              F=script_api::call_tool_init (__cdecl *)(consist_t *,const char *)
1>          ]
1>  c:\users\james\documents\development\simutrans\sources\trunk\script\api\../api_function.h(269): note: while compiling class template member function 'std::string script_api::func_signature_t<F>::get_squirrel_type(bool,int)'
1>          with
1>          [
1>              F=script_api::call_tool_init (__cdecl *)(consist_t *,const char *)
1>          ]
1>  c:\users\james\documents\development\simutrans\sources\trunk\script\api\../api_function.h(109): note: see reference to function template instantiation 'std::string script_api::func_signature_t<F>::get_squirrel_type(bool,int)' being compiled
1>          with
1>          [
1>              F=script_api::call_tool_init (__cdecl *)(consist_t *,const char *)
1>          ]
1>  c:\users\james\documents\development\simutrans\sources\trunk\script\api\../api_function.h(105): note: see reference to class template instantiation 'script_api::func_signature_t<F>' being compiled
1>          with
1>          [
1>              F=script_api::call_tool_init (__cdecl *)(consist_t *,const char *)
1>          ]
1>  script\api\api_consist.cc(204): note: see reference to function template instantiation 'void script_api::register_method<script_api::call_tool_init(__cdecl *)(consist_t *,const char *)>(HSQUIRRELVM,F,const char *,bool,bool)' being compiled
1>          with
1>          [
1>              F=script_api::call_tool_init (__cdecl *)(consist_t *,const char *)
1>          ]
1>c:\users\james\documents\development\simutrans\sources\trunk\script\api\../api_function.h(477): error C3861: 'get': identifier not found
1>  ai_goods.cc
1>player\ai_goods.cc(316): warning C4244: 'argument': conversion from 'sint16' to 'uint8', possible loss of data
1>player\ai_goods.cc(326): warning C4244: 'argument': conversion from 'sint16' to 'uint8', possible loss of data
========== Build: 0 succeeded, 1 failed, 0 up-to-date, 0 skipped ==========

Edit: The patch that is giving me these errors is here (http://bridgewater-brunel.me.uk/downloads/language-translation-1.patch).
Title: Re: German in the code
Post by: Dwachs on November 26, 2016, 04:39:57 PM
Somehow you did not patch script/api_param.h

But why would you replace convoy with consist? I think there are more urgent things to translate?
Title: Re: German in the code
Post by: jamespetts on November 26, 2016, 05:10:02 PM
Ahh, thank you. That file was missing from the Visual Studio solution for some reason. A corrected patch is here (http://bridgewater-brunel.me.uk/downloads/language-translation-1a.patch).

The reason that I am doing them in this order is that I think that it is probably more efficient simply to go through the above in list order and keep going until it is all done.
Title: Re: German in the code
Post by: Dwachs on November 26, 2016, 06:04:33 PM
Personally, I do not like the change convoy -> consist.
Title: Re: German in the code
Post by: jamespetts on November 26, 2016, 06:07:51 PM
Personally, I do not like the change convoy -> consist.

We have to choose something, and that seems to be the clearest of all the suggestions so far. May I ask what you dislike about it?

I had hoped that any issues such as this could have been identified before I actually produced the patch, which is why I posed the question earlier.
Title: Re: German in the code
Post by: Dwachs on November 26, 2016, 07:53:53 PM
It is just out of nostalgia, and the feeling that this change is not the most pressing issue. For instance, the convoy/consist interface could need translation. I do not want to play gatekeeper here, if there is support for this idea, then I will apply the patch.

What is your plan? You want to apply the list line by line? My idea was to do the translation in file by file (or directory by directory). Or at least in logical units: all grund_t, all *_Besch_t, etc.

I always read your as if it were your private list to help understand some German words.
Title: Re: German in the code
Post by: jamespetts on November 26, 2016, 08:37:21 PM
The idea is indeed to apply the list line by line: that is one of the the reasons that I compiled it. I have not sought to prioritise any of the translations compared to others because the idea is to do all of it as fast as possible, and thinking about the order in which to do them will take unnecessary time. If they are all done quickly, then the sequence will make little difference. The importance of speed is that the prevalence of non-English words in the code appears to act as a serious deterrent to would-be developers.
Title: Re: German in the code
Post by: Ters on November 26, 2016, 10:02:32 PM
You should at least take the undisputed things first, so that you don't waste time doing the wrong translation or getting stuck waiting for a decision to be made. I'm not sure convoi, besch and the grund/boden things have been settled.
Title: Re: German in the code
Post by: jamespetts on November 26, 2016, 10:48:24 PM
I did not realise that these things were disputed - that is why I posted the list and asked whether people were in agreement with it. Does anyone have any better ideas for "convoi" than "consist"? If not, surely it is better to have "consist" than retain "convoi", which is not an English word?
Title: Re: German in the code
Post by: prissi on November 26, 2016, 11:00:44 PM
consist is only trains, but not cars, tugs, or anything else. And cnv is really heavenly used in the code. Third, convoi is not German either.
Title: Re: German in the code
Post by: Jim Knopf on November 26, 2016, 11:55:36 PM
Are you sure with that the translation gerade = just?

One of the meanings of "gerade" is really "just". But I guess that "straight" is what the simutrans code means.
Title: Re: German in the code
Post by: Ters on November 27, 2016, 12:06:38 AM
Are you sure with that the translation gerade = just?

One of the meanings of "gerade" is really "just". But I guess that "straight" is what the simutrans code means.

I've already mentioned that, which shows that jamespetts keeps working from an outdated list. And considering how the discussion went in every which way because there were a lot of words to decide on at once, keeping the list up-to-date is not easy.
Title: Re: German in the code
Post by: An_dz on November 27, 2016, 12:38:07 AM
convoi = convoy
convoy = vehicle
Title: Re: German in the code
Post by: jamespetts on November 27, 2016, 11:27:43 AM
The word "consist" in its American usage to refer to the vehicles of which a train consists seems equally apt to apply, for Simutrans purposes, to other sets of vehicles which run together (such as a horse pulling a carriage or canal boat or an articulated lorry). Certainly, there is not another word that describes things so clearly; even the word that I had suggested earlier, "assemblage", is not clearer. The fact that the use of "consist" is railway specific is probably because there is no particular reason to refer to such things outside the railway context with that degree of specificity, and a loose use of "vehicle" will suffice for an articulated lorry or horse and carriage.

In any event, surely "consist" is better than "convoi", which is not an English word at all, but resembles the English word "convoy" which means something different entirely?

As to the uses of "cnv", as you will note from looking at the patch, this changes "cnv" to "cnst" to match "consist".

If people would like to agree on a word other than "consist" (such as "assemblage", although that might give the somewhat unfortunate "****" as an abbreviation; one is put in mind of donkey-drawn carriages, I suppose), I can update my patch for that other word, but we really do need something other than "convoi" if we are to make the code consistently use English words.

As to "gerade", I note the improved translation suggestion and will add that to the next revision of the list. The reason that I have a long list, incidentally, is that it is intended to be as comprehensive as possible, as it is important, for the purpose of encouraging new coders, to be as thorough and as swift as possible in this project. If I have made any other errors in my latest list, please do let me know so that I can produce an improved version.
Title: Re: German in the code
Post by: Dwachs on November 27, 2016, 02:02:47 PM
I modified the list. Imho some proposals do not sound right
  • get_zeit_ms (get_ticks)
  • vorgaenger (leading) - leader
  • nachfolger (trailing) - follower
  • convoi (consist) - should stay
  • convoihandle (consist_handle) - should stay
  • fussgaenger_besch_t (pedestrian_base_type_t) - pedestrian_desc_t
  • besch (desc)
  • tile_t (stop_tile_t)
  • grund (tile)
  • gr (tile)
  • boden (ground)
  • bd (gr)
  • gebaeude (building)
  • stadt (city)
  • fabrik (industry)
  • fundament (foundation)
  • planquadrat (grid_square)
  • platzsucher (location_finder)
  • simfab (simindustry)
  • warenziel (cargo_destination)
  • wasser (water)
  • zeiger (pointer)
  • raucher (smoke_producer)
  • vehikel (vehicle)
  • bauer (builder)
  • linien (line) - linie to line, linien to lines
  • schiene (railway) - track
  • strasse (road)
  • bauigel (constructor)
  • route_fuer (route_for)
  • ribi (direction_bits - I know that this is longer, but it makes what this is about so much clearer))
  • laden (load)
  • ist_ (is_)
  • optionen (options)
  • kennfarbe (colour)
  • farbengui_t (colour_gui_t)
  • haus (structure - this cannot also be "building")
  • kanal (canal)
  • karte (map)
  • liefere_an (supply) - supply_factory
  • starte_mit_route (start_with_route)
  • get_ware_fuer_zielpos (get_cargo_for_destination_pos)
  • get_ware_summe (get_cargo_amount)
  • ware (cargo)
  • liefere_an_fabrik (deliver_to_factory)
  • sortierung (sorting)
  • welt (world)
  • koord (coord)
  • haltestellen (stops)
  • haltestelle (stop)
  • halthandle (stop_handle)
  • halt (stop) - why change this?
  • verbrauch (consumption)
  • kapazitaet (capacity)
  • platzierung (placement)
  • produktivitaet (productivity)
  • bereich (range)
  • gewichtung (chance)
  • lieferanten (suppliers)
  • produkte (products)
  • rauch (smoke)
  • fab (ind)
  • verteile (distribution) - distribute
  • ausgang (exit) - output
  • eingang (entry) - input
  • vorrat_an (stockpile)
  • baue (build)
  • hierarchie (chain)
  • zufallsbauplatz (random_building) - random_building_place/site
  • finde (find)
  • sucher (search) - searcher?
  • hersteller (producer)
  • bauplatz (place_to_build)
  • spezial (special)
  • bau (build)
  • bewerte (check_value)  - evaluate[/b]
  • wachstum (growth)
  • zufallspunkt (random_point)
  • arbeiterziel (workplace)
  • senke (sink)
  • pumpe (source)
  • linksoben (top_left)
  • rechtsunten (bottom_right)
  • lo (tl)
  • ur (br)
  • bruecke (bridge)
  • baum (tree)
  • karten_boden (surface)
  • natur (empty)
  • verbindung (connexion) - why x? connection

The following words are already translated: bild, eintrag, fahrplan, position_bei, fpl, anzahl, hang, gerade, doppelr,
the ribi_t and hang_t interface, ow, hole_ab. There is no point to argue about 'gerade', it is already translated to 'straight'.
Title: Re: German in the code
Post by: jamespetts on November 27, 2016, 03:42:18 PM
Thank you very much for that; that is helpful.

Is liefere_an() not also used for things other than factories, or is that just in Experimental? As to "convoi", see my comments above on this issue. In respect of "halt", the word "halt" in English as a noun is typically used to refer specifically to very small rural railway stations: "stop" is the more generic name. Is there a reason that you have put "this cannot also be 'building'" in bold above? As to "connexion", this is the traditional British (rather than American) spelling, and it is used extensively already in Experimental.

Aside from the above issues, do we have consensus on these translations as annotated by Dwachs now?
Title: Re: German in the code
Post by: An_dz on November 27, 2016, 04:57:39 PM
In respect of "halt", the word "halt" in English as a noun is typically used to refer specifically to very small rural railway stations: "stop" is the more generic name.
I find "halt" better because even though it's only used as "rural railway stations" as you said it's better than a "loose" word as "stop", which has multiple meanings, including being a very common verb.

Is there a reason that you have put "this cannot also be 'building'" in bold above?
Either because "building" is already used in another context in the code or Dwach forgot a question mark.

sucher (search) - searcher?
Finder?

The word "consist" in its American usage to refer to the vehicles of which a train consists seems equally apt to apply, for Simutrans purposes, to other sets of vehicles which run together (such as a horse pulling a carriage or canal boat or an articulated lorry).
The problem with "consist" is that, to us non-natives, its usage as a noun does not exist. We think about the verb and the verb is a term for defining anything that is composed of something.

In any event, surely "consist" is better than "convoi", which is not an English word at all, but resembles the English word "convoy" which means something different entirely?
No, "convoy" is "convoi" but ending with Y. The British got the French word (convoi) and for some reason changed the "I" to an "Y".

As I said before, language is a bunch of made up words and copies of other languages.

For example, as you've noted "assemblage" is an English word, right? Wrong, it's French. Now it's on the English dictionaries but it's 100% equal to the French word. Of course the pronunciation is different, but "assemblage" is merely a copy of French just as "convoy" is "convoi".

What I see is that both "convoi" and "convoy" are used in the code and then their usages are different. Where "convoi" is used it's in the same meaning as "convoy", but where "convoy" is used it's just for a single vehicle. But, maybe, in English a "vehicle" has to contain a motor - it has to pull itself -, while in the Simutrans code "convoy" is used for any piece, including carts and trailers. But I still think that "convoy" should be changed to "vehicle" and "convoi" to "convoy".
Title: Re: German in the code
Post by: Ters on November 27, 2016, 05:00:26 PM
Should we give everybody time to give their opinion? Not every developer has so yet. Not that we can wait forever.

What I see is that both "convoi" and "convoy" are used in the code and then their usages are different. Where "convoi" is used it's in the same meaning as "convoy", but where "convoy" is used it's just for a single vehicle. But, maybe, in English a "vehicle" has to contain a motor - it has to pull itself -, while in the Simutrans code "convoy" is used for any piece, including carts and trailers. But I still think that "convoy" should be changed to "vehicle" and "convoi" to "convoy".

There are no convoys in Simutrans by the definition of the word I know. A convoy is a group of independent vehicles travelling together as a group, convoi_t is either a single independent vehicle or multiple dependent and optionally independent vehicles joined together as a supervehicle.
Title: Re: German in the code
Post by: jamespetts on November 27, 2016, 05:08:20 PM
An_Dz

"Stop" is very commonly used to refer to a place that a transport service with a regular schedule stops: indeed, it is the most standard way of describing this. "Halt" is quite obscure in this context. I do think that "stop" is clearer here. What are others' views?

"Finder" seems sensible.

As to whether something is an English word or not, I refer not to its origin (as almost every word in English has its origin in some forebear language that is not English), but to whether that word with that spelling will be found in an English dictionary. It is thus not wrong to say that "assemblage" is an English word in that sense though it has its roots in French. It is in that sense that "convoi" is not an English word, and that is why it is important to change it. The aim of this exercise is to standardise upon one widely spoken language for the names of variables, functions, classes and files in the code. That aim is not served by retaining non-English words such as "convoi".

As to "vehicle", the standard English usage of this word does not require that it be powered (so a railway carriage or a horse drawn cart are both considered to be vehicles), and the word "vehikel" (which needs to be translated to "vehicle") is currently used in the code to refer to the individual vehicles rather than to assemblages of them. As noted before, "convoy" refers to a succession of independently operated vehicles rather than to something like a train where multiple vehicles are connected together and driven as one. Thus, not "vehicle", "convoy" nor "convoi" is suitable to be used where "convoi" is currently used in the code.

Ters

How long do you suggest?
Title: Re: German in the code
Post by: kierongreen on November 27, 2016, 06:07:19 PM
From Dwachs list I agree with him about pedestrian_desc, track, distribute, output, input, halt and connection. I also agree with convoy being preferable to consist.

The rest I don't have any strong feelings about.
Title: Re: German in the code
Post by: isidoro on November 27, 2016, 09:03:36 PM
To add to the debate: I would keep convoi and halt.  Reason is practical: those words didn't pose a problem to me when dealing with the code for the first time.  Just the opposite with the other words.  So, it isn't worth the effort to change them.
Title: Re: German in the code
Post by: jamespetts on November 27, 2016, 09:14:46 PM
To add to the debate: I would keep convoi and halt.  Reason is practical: those words didn't pose a problem to me when dealing with the code for the first time.  Just the opposite with the other words.  So, it isn't worth the effort to change them.


As to the effort, I should note that I have already expended the effort in creating a patch for Standard changing "convoi" to "consist", so this is not an issue. It would actually have to be better overall, in the long-term for the word "convoi" to continue to be used in the code for there to be a reason to keep this.
Title: Re: German in the code
Post by: prissi on November 27, 2016, 10:56:39 PM
I still would like to keep thing not tranlating because it feels better. Programming is about abstraction.

Whether is is halt or stop, or convoi or consist its abstract function will be the same. But renaming will either create inconsitiencies in the scripting or require again changing of script for tutorials etc.

And about following vehicle, I still think trailer is a better translation than follower (which I expect is not neccessarily connected to the leader). That was why I suggested leading/trailing (and for factories then supplying and producing for the hersteller/verbraucher there).

Also senke is rather drain, as it drains the current (and in transistors/diodes there is also source and drain).

input/output may clash with libraries. I think that goods_in and goods_out can do the trick even better.

I find nowhere in the code optionen, only as a file name (which would be then option_frame) Same for simfab. But renaming may throw away change log.

My comments on Dwachs comment on the original list:
  • get_zeit_ms (get_ticks)
  • vorgaenger (leading)  s.a.
  • nachfolger (trailing)
  • convoi not renaming
  • tile_t (stop_tile_t)
  • grund (tile)
  • gr (tile)
  • boden (ground)
  • bd (gr)
  • gebaeude (building)
  • stadt (city)
  • fabrik (industry)
  • fundament (foundation)
  • planquadrat (grid_square) - maybe grind_tile?
  • platzsucher (location_finder)
  • simfab (simfactory) - where is this in the code?
  • warenziel (destination) - also for passengers and mail so no cargo_ prefix
  • wasser (water)
  • zeiger (indicator) - because pointer is something else in C++
  • raucher (smoker) - because those produce smoke anyway
  • vehikel (vehicle)
  • bauer (builder)
  • linien (line) - linie to line, linien to lines
  • schiene (railway) - track
  • strasse (road)
  • bauigel (constructor)
  • route_fuer (route_for)
  • ribi (dirs) - since it is used so much
  • dirs (haedings) - since it is used much less
  • laden (loading) - since that is what it does
  • ist_ (is_)
  • farbengui_t (colour_gui_t)
  • haus (structure - this cannot also be "building")
  • kanal (canal)
  • karte (map)
  • liefere_an (dispatch OR handling OR receive) - because the stop recieves that paket and will handle it further
  • starte_mit_route (start_with_route)
  • get_ware_fuer_zielpos (get_cargo_for_destination) the _pos seems superfluous
  • get_ware_summe (get_cargo_amount)
  • ware (cargo)
  • liefere_an_fabrik (deliver_to_factory)
  • sortierung (sorting)
  • welt (world)
  • koord (coord) again, without diving into regions, there are three different coords, like scr_coord and map_coord (2D) and tile_coord (3D) That renaming would go beyond simple text replacing, if done properly.
  • haltestellen (all_halt) - as said, halt seems to me more a station thing, while stop includes red signals, crossings and traffic lights
  • haltestelle (halt) - dito
  • halthandle (halt_handle) - dito
  • halt (halt)  - dito
  • verbrauch (consumption)
  • kapazitaet (capacity)
  • platzierung (location) - since it is coast etc.
  • produktivitaet (productivity)
  • bereich (range)
  • gewichtung (chance)
  • lieferanten (suppliers)
  • produkte (products)
  • rauch (smoke)
  • fab (fac OR fact) - forest or fisheries are rarely industries, which seems rather name an entire chain
  • verteile (distribution) - distribute
  • ausgang (goods_in) - exit and entry as well as output and input are dangerously close to future resevered keywords or library routines
  • eingang (goods_out) - dito
  • vorrat_an (stockpile)
  • baue (build)
  • hierarchie (chain)
  • zufallsbauplatz (random_building) - random_building_place/site
  • finde (find)
  • sucher (finder) - to be consistent
  • hersteller (producer)
  • bauplatz (place_to_build) - building_site?
  • optionen (options)
  • kennfarbe (colour)
  • bau (build)
  • bewerte (evaluate) - yeah, I prefer verbs
  • wachstum (growth)
  • zufallspunkt (random_coord)
  • arbeiterziel (workplace)
  • senke (drain) - at least in electronics it is source to drain currents in transistors ...
  • pumpe (source)
  • linksoben (upper_left) not care too much, could live with top_ too
  • rechtsunten (bottom_right)
  • lo (upper_left) - write them out to make clear, only a few places anyway
  • ur (bottom_right) - dito
  • bruecke (bridge)
  • baum (tree)
  • karten_boden (surface)
  • verbindung (connexion) - x seems strange to me too, would prefer connection

Some I could not find ...
  • natur (empty) - not in the code???
  • spezial (special) - not in the code???
Title: Re: German in the code
Post by: jamespetts on November 27, 2016, 11:39:23 PM
Prissi,

thank you: that is very helpful. The ribi/dirs suggestion is a good one, as it keeps this as short as it was originally intended. I do prefer "leading" and "trailing", as these participle verbs are often used as adjectives in English.

As to factory/industry, "industry" refers traditionally just to people doing productive work, being the abstract noun form of "industrious". It is only in the 19th century that it became a non-abstract noun to refer to what were then modern means of production. "Industry" thus applies to anything that is covered by the "fabrik_t" class in Simutrans. "Factory", on the other hand, comes from "Manufactory", a place where goods are manufactured. Its meaning is thus much narrower than "industry", and would not be apt to cover mines, farms, fisheries or shops in the way that "industry" would. "Ind" is a good abbreviation for "industry".

spezial_filter can be found in convoi_frame.cc.

I cannot find "natur" either now - it may have been included in error, although I am not sure from where it comes.

Splitting the different types of co-ordinates for different purposes (as in scr_coord) can be done after and separately to changing "koord" to "coord".
Title: Re: German in the code
Post by: Ters on November 28, 2016, 06:05:51 AM
Also senke is rather drain, as it drains the current (and in transistors/diodes there is also source and drain).

Transistors seems to be the only case which uses drain with source. Source-sink seems to be (https://en.wikipedia.org/wiki/Source%E2%80%93sink_dynamics) quite the established pair (https://en.wikipedia.org/wiki/Current_sources_and_sinks) in other fields. Perhaps most importantly here: graph theory (https://en.wikipedia.org/wiki/Directed_graph#Indegree_and_outdegree). This (https://en.wikipedia.org/wiki/Sink_(computing)) is perhaps not relevant, though.
Title: Re: German in the code
Post by: prissi on November 28, 2016, 08:54:20 PM
Well, the device which does the current sinking, is called a programmable load. Maybe source and load?
Title: Re: German in the code
Post by: jamespetts on November 29, 2016, 08:58:47 PM
We probably ought to use the correct terminology that apply to substations in the real world, ought we not?
Title: Re: German in the code
Post by: prissi on November 29, 2016, 09:19:46 PM
The end user is a consumer, but that is already in use elesewhere ...
Title: Re: German in the code
Post by: jamespetts on November 29, 2016, 09:22:45 PM
One could have "consumer_substation" and "producer_substation"?
Title: Re: German in the code
Post by: prissi on December 07, 2016, 10:27:11 PM
bild_besch.h/cc contains now the image_t type and no single instance of bild anymore. Maybe also rename this to image_besch.h/cc?
Title: Re: German in the code
Post by: jamespetts on December 07, 2016, 10:59:24 PM
bild_besch.h/cc contains now the image_t type and no single instance of bild anymore. Maybe also rename this to image_besch.h/cc?

This seems sensible to me. Sorry that I have not had a chance to progress this of late: I have been spending all of my Simutrans time trying to track down and fix some very difficult desync bugs.
Title: Re: German in the code
Post by: Dwachs on December 11, 2016, 07:36:17 PM
I am in the process of translating the besch folder. I have some questions. How to translate the following strings :
Code: [Select]
fabrikbauer_t::ist_bauplatz -> check_construction_site
fabrikbauer_t::finde_zufallsbauplatz -> find_random_construction_site
haus_besch_t::get_h / get_w -> get_x / get_y   (get_height is ambigous here, get_h returns x-size of building)
Title: Re: German in the code
Post by: jamespetts on December 11, 2016, 08:01:36 PM
I think that your suggestions are sensible. Thank you for working on this, incidentally.
Title: Re: German in the code
Post by: Dwachs on December 11, 2016, 08:36:54 PM
More questions:
Code: [Select]
hausbauer -> house_builder??
neues_gebaeude -> build_station_extension_depot ?? - this routine builds stations, extension buildings, and depots
Another possibility would be to split hausbauer into building_manager_t (that manages all the lists of building types) and house_builder_t (that does the construction of buildings on the map).

Edit: What to do with the methods with semi-German names in obj_desc_transport_related_t? For all of them, English equivalents are already available. Change?

Edit2: How to translate skin_besch_t? It is a list of image with associated name and author name...
Title: Re: German in the code
Post by: Ters on December 12, 2016, 06:48:29 AM
Edit2: How to translate skin_besch_t? It is a list of image with associated name and author name...

When encountered on their own, they are mostly images for the GUI, so they are skins. When used as cursors for other types, they are just odd by having their own name and copyright.
Title: Re: German in the code
Post by: Dwachs on January 07, 2017, 04:30:44 PM
I submitted now a number of commits to translate all the besch and bauer classes. Still there are some things to translate:
How to translate:
Code: [Select]
ware_besch_t -> good_desc_t ?
ware_besch_t::get_preis -> ..::get_revenue ?
warenbauer_t -> good_manager_t ? (in resemblance of good_write_t and good_reader_t)
Should these members be renamed
Code: [Select]
way_desc_t::styp -> systemtype
way_desc_t::get_styp -> get_systemtype ?
After this is finished, I will rename all the files, and the directories
Code: [Select]
bauer -> builder ?
besch -> descriptor ?
Title: Re: German in the code
Post by: jamespetts on January 07, 2017, 04:38:46 PM
This is excellent work, and apologies again that I have not had a chance to help with this yet. Most of the above suggestions are sensible, but may I suggest alternatives in two cases:

good_desc_t would be better as goods_desc_t; and

descriptor would be better as base_type, as the concept of a descriptor is of a description rather than a definition, which is not, to my mind, the same thing.
Title: Re: German in the code
Post by: Dwachs on January 07, 2017, 07:16:56 PM
Why the plural word in goods_desc_t? All other class names use singular forms.

Also 'descriptor' was meant to be the renaming of the besch-directory. In the code, I have translated besch to desc.
Title: Re: German in the code
Post by: An_dz on January 07, 2017, 08:30:37 PM
Because in English the only word that describe the Simutrans idea of products, manufactured stuff or wares is goods that only exists in plural form.
Title: Re: German in the code
Post by: Ters on January 07, 2017, 10:00:46 PM
Because in English the only word that describe the Simutrans idea of products, manufactured stuff or wares is goods that only exists in plural form.

For Simutrans, I think the other definition of goods in my Oxford dictionary is the one that applies here (which is called freight in US English according to the same dictionary), but the word is the same and so are the rules. Although I'm not sure they intended their definition ("things carried by trains") to include passengers, although perhaps mail, neither of them fit the first ("things for sale") in modern civilization. Except top athletes, apparently.
Title: Re: German in the code
Post by: Dwachs on January 08, 2017, 10:07:23 AM
Did not know about this plural thing :) What about
Code: [Select]
ware_t -> freight_t ?
Title: Re: German in the code
Post by: jamespetts on January 08, 2017, 10:15:37 AM
Did not know about this plural thing :) What about
Code: [Select]
ware_t -> freight_t ?

Might that not be confusing as "ware" includes passengers?
Title: Re: German in the code
Post by: Vladki on January 08, 2017, 11:23:59 AM
I'm not native english neither german, but for me freight and cargo seem more general than goods (or german waren). But neither would include passengers. OTOH I dont know what word to use that includes passengers, mail and goods together.

I don't know whether t_ware includes pax in simutrans or not.
Title: Re: German in the code
Post by: Dwachs on January 08, 2017, 11:44:29 AM
The class ware_t refers to stuff loaded into trains, whereas ware_besch_t describes different types of freight/goods. Their translations should somehow reflect this and should be easily distinguishable:
Code: [Select]
ware_besch_t -> goods_desc_t
ware_t -> freight_t, cargo_t?
How should single occurences of goods descriptions be called?
There are methods get_ware in factory descriptions to describe consumed and produced goods. There are also variables of goods descriptors called 'ware'.
How to translate them
Code: [Select]
factory_supplier_desc_t::get_ware -> ??
const ware_besch_t* ware -> const goods_desc_t*  goods_type ??? too long
Title: Re: German in the code
Post by: An_dz on January 08, 2017, 02:15:53 PM
Why translate ware? Ware is English and fits:

https://en.wiktionary.org/wiki/ware#Etymology_2
http://www.wordnik.com/words/ware

Quote
from The American Heritage® Dictionary of the English Language, 4th Edition

n. An article of commerce.
n. An immaterial asset or benefit, such as a service or personal accomplishment, regarded as an article of commerce.
Title: Re: German in the code
Post by: Ters on January 08, 2017, 04:10:30 PM
Ware is a word in commerce, not in logistics. Simutrans is generally about logistics. However, there seems to be an issue whether we should translate into British English or American English.
Title: Re: German in the code
Post by: sdog on January 08, 2017, 09:00:24 PM
Cargo?

http://www.etymonline.com/index.php?term=cargo
Quote
cargo (n.) 
1650s, "freight loaded on a ship," from Spanish cargo "burden," from cargar "to load, impose taxes," from Late Latin carricare "to load on a cart" (see charge (v.)).
Title: Re: German in the code
Post by: isidoro on January 08, 2017, 11:42:08 PM
What about payload or haul?

I'm not a native speaker.  Just found them searching in the web.
Title: Re: German in the code
Post by: An_dz on January 09, 2017, 12:59:17 AM
Let's just remember that we are translating to help anyone in the world who speaks some English to better understand the code and not to be a dictionary.

Let us stick with more obvious words that non-natives can understand and not just a British can.

So I vote for cargo or goods.
Title: Re: German in the code
Post by: Ters on January 09, 2017, 07:06:31 AM
I'm leaning towards goods_desc_t and cargo_t. The former isn't really about cargo, although it is about something that exists for the purpose of potentially becoming cargo. Goods feels more right (or less wrong) when dealing strictly with the consumer-supplier relationship.

The legacy warenziel_t should probably follow the cargo rule. warenbauer_t seems more like a goods_type_manager_t (or some would probably argue goods_types) than either goods_builder_t or cargo_builder_t.
Title: Re: German in the code
Post by: Leartin on January 09, 2017, 07:45:19 AM
 ??? Isn't the issue Dwachs has that currently, 'ware_t' includes pax, while 'ware_besch_t' does not - and now he is looking for two words that reflect that difference?

However, I don't think a proper umbrella term for both exists - this is because googling for one does give results in logistics literature, but only constructed terms like "transported objects"

Since it obviously makes sense to use two different terms, we would have to redefine one of the many synonyms for goods to include pax, and another to not include pax. As such, my vote is for "goods" to exclude pax and "freight" to include pax.

Reasoning:
to me, freight stresses 'stuff that's transported'. It's secondary what kind of stuff it is, and primary that it gets moved around.
while goods are 'a product, something tangible, something of commercial value' -so primarily a thing.

Technically, factorys can't produce freight. They only produce goods. Technically, if you put people in the back of a truck, they become freight.
Title: Re: German in the code
Post by: Ters on January 09, 2017, 04:44:00 PM
??? Isn't the issue Dwachs has that currently, 'ware_t' includes pax, while 'ware_besch_t' does not - and now he is looking for two words that reflect that difference?

No. ware_besch_t does also cover passengers and mail (these are both mandatory, the rest are optional and does not have specific logic attached). It is how the revenue and speed bonus are set for them, just like the rest. Each line in the list in the Goods List window corresponds to a ware_besch_t. Come to think of it, that gives something of a precedent for translation of ware in ware_besch_t.

to me, freight stresses 'stuff that's transported'. It's secondary what kind of stuff it is, and primary that it gets moved around.
while goods are 'a product, something tangible, something of commercial value' -so primarily a thing.

Technically, factorys can't produce freight. They only produce goods. Technically, if you put people in the back of a truck, they become freight.

If it matters, freight is apparently an American English word. British English uses goods in both cases, according to Oxford University Press in 1998 at least. But, yes, I agree that freight can not be used for all cases.
Title: Re: German in the code
Post by: prissi on January 11, 2017, 01:15:50 PM
Since ware is an english word meaning exactly the same as the german one, why not keep it. Keeps for oldtimers like me the understanding of the code the same and possibly also less work for DrSuperGood with his patches ...
Title: Re: German in the code
Post by: jamespetts on January 11, 2017, 05:44:32 PM
"Ware" would work for freight, but surely not for passengers?
Title: Re: German in the code
Post by: rainer on January 12, 2017, 01:24:46 PM
What about "payload"?
Title: Re: German in the code
Post by: prissi on January 12, 2017, 03:20:16 PM
I would not touch it. Goods and the goods_desc also cover passengers and mail, so ware would have the same logic. Focussing on something which is more German and less easy to understand seems a better use of time.
Title: Re: German in the code
Post by: An_dz on January 12, 2017, 05:08:37 PM
I agree, ware is also English and it's easy to understand. I'll stress again:

Let's just remember that we are translating to help anyone in the world who speaks some English to better understand the code and not to be a dictionary.

Let us stick with more obvious words that non-natives can understand
Title: Re: German in the code
Post by: Ters on January 12, 2017, 05:16:12 PM
I do however think that there is some value in using the same terms in the code as is used in the user interface.
Title: Re: German in the code
Post by: Vladki on January 12, 2017, 06:43:08 PM
Perhaps also take into acconunt words used as dat file options
Title: Re: German in the code
Post by: jamespetts on January 27, 2017, 07:29:06 PM
I see that a great amount of work has been done on this lately: I have just caught up with getting these translations into Experimental. I notice, however, that, in some cases (e.g. all of the old "besch" classes), the filenames have not been amended whereas the class names have, resulting in filenames being out of sync with class names.

Would it be helpful if I were to submit a patch to rename the files, too? One slight complication to this may be that my Visual Studio project has been modified from the base as I found that I could not get it to compile otherwise (and I am using Visual Studio 2015).

In the meantime, I will see if I can submit a patch for some of the miscellaneous translations in Prissi's post above that have yet to be implemented.

Edit: Further to my earlier post, here (http://bridgewater-brunel.me.uk/misc/welt-to-world.patch) is a patch to translate welt to world (including renaming the existing world() function to get_world() to avoid clashes).
Title: Re: German in the code
Post by: Dwachs on January 29, 2017, 05:12:52 PM
I planned to do the renaming after all classes have been translated. Got stuck at translating the ware stuff.
Title: Re: German in the code
Post by: jamespetts on January 29, 2017, 05:47:58 PM
Would it be easier if I were to leave the translating to you, or would it be helpful if I were to submit more translation patches? I am more than happy to help but I do not want to spend time on this if it will not be useful.

Also, what difficulty are you having with translating the ware classes?
Title: Re: German in the code
Post by: Dwachs on January 30, 2017, 08:07:40 AM
It would be enough to suggest / discuss translations. The patching itself is then an easy (still time-consuming) task. The difficulty was to find translations that reflect the use in the program and still correspond to real-life English.
Title: Re: German in the code
Post by: jamespetts on January 30, 2017, 11:30:55 AM
Ahh, I see. Is the welt/world patch above useful? What difficulties were you having in the ware_t classes?
Title: Re: German in the code
Post by: Ters on January 30, 2017, 05:16:02 PM
Have you forgotten the big discussion about those already?
Title: Re: German in the code
Post by: jamespetts on January 30, 2017, 08:34:40 PM
Quite possibly: I have done a lot of work on Experimental in the meantime. Perhaps we should mark out the problematic keywords, set them aside with a discussion with a deadline for a decision and a voting mechanism to allow for a majority decision, and in the meantime work on the easier keywords?

Would it help if I were to suggest more translations?
Title: Re: German in the code
Post by: Dwachs on January 30, 2017, 08:57:03 PM
James: Thanks for bringing this up again. It is hard to review such big patches (you translate new_world -> new_get_world?). If this change (welt -> world) would help anything, I can throw it in. But there are still 'welt'names objects, (get_weltpos, gui/welt.h etc).

Here is an updated list of terms including 'ware' with proposed translations. This list should not be too controversial:
Code: [Select]
ware_besch_t -> goods_desc_t  (types of goods/freight, e.g., Passenger, Coal)
good_reader_t -> goods_reader_t -> add 's'
good_writer_t -> goods_writer_t -> add 's'
warenbauer_t -> goods_manager_t -> to be inline with goods_reader/writer
I did not see a conclusion of the discussion for the following ones:
Code: [Select]
ware_t --> cargo_t (to be as short as before)  - these is freight with destination (e.g., 10 people going to Berlin, 20t of Coal to the north pole)
ware variables/parameter -> ware (?)
There are get_ware* methods. What to do with them:
Code: [Select]
factory_supplier_desc_t::get_ware - type of goods consumed by a factory (dat-file parameter: "inputgood") -> get_input / get_type ?
factory_product_desc_t::get_ware -  type of goods produced by a factory (dat-file parameter: "outputgood")-> get_output / get_type ?
vehicle_desc_t::get_ware - type of goods transported by a vehicle (dat-file parameter: "freight"), similar method: vehicle_t::get_cargo_type -> use this name?
Also haltestelle_t (halts) has quite a few get_ware_* methods.
Title: Re: German in the code
Post by: jamespetts on January 30, 2017, 09:10:39 PM
The suggestions made in the first two code boxes seem sensible to me.

As to the last, I prefer "get_output" to "get_type", as it seems to indicate more clearly what is happening.

In the meantime, here is a list of one or two other miscellaneous translation suggestions:

merke_passagier_ziel > mark_passenger_destination
liefere_an_fabrik > deliver_to_factory
liefere_an > deliver_to_factory_without_route
starte_mit_route > deliver_to_factory_with_route
menge > amount
gibt_ab > accepts_type
get_ware_fuer_zielpos > get_goods_for_destination_pos ("_pos" might be omitted if it is clear that we are not referring to a destination stop)
get_ware_fuer_zwischenziel > get_goods_for_transfer
get_ware_summe > get_goods_total
vereinige_waren > merge_goods
verbinde_fabriken > connect_factory_to_halt (or possibly just connect_factory)
haltestelle_t > stop_t
halthandle_t > stop_handle_t
alle_haltestellen > all_stops
Title: Re: German in the code
Post by: Vladki on January 30, 2017, 10:14:14 PM
As to the last, I prefer "get_output" to "get_type", as it seems to indicate more clearly what is happening.

I would suggest something like get_output_type, so that it is clear that you are interested in type of output goods, and not about the output capacity, or current storage. (I admit I did not look into the sources ;)
Title: Re: German in the code
Post by: Ters on January 31, 2017, 06:34:48 AM
I'm with Vladki on that last one. It matches up with a similar function on vehicle_t. Which means that at least this one isn't a case of n proposals with one vote each.
Title: Re: German in the code
Post by: jamespetts on January 31, 2017, 12:29:54 PM
Seems sensible.
Title: Re: German in the code
Post by: prissi on February 02, 2017, 11:16:08 AM
I am still somewhat opposed to rename ware for goods, as this is english unlike a lot of other stuff. (And before someone suggest to use stuff instead of goods, as it covers passengers too ;)

But if renaming, I suggest accepts_type should be accepts_good.
Title: Re: German in the code
Post by: Dwachs on February 02, 2017, 12:56:09 PM
I completed the translation of besch stuff including renaming of files locally on my computer.

My proposal would be to translated ware(n) to cargo or freight.
Title: Re: German in the code
Post by: prissi on February 03, 2017, 10:53:28 AM
We covered that some pages before ... Aparently freight or cargo is only stuff moving, while ware (or goods) can be also stationary (so "ware house" or "goods shed"). So it seems rather ware or goods was the conclusion.

(But I contributed so little lately, I leave it to you.)
Title: Re: German in the code
Post by: An_dz on February 16, 2017, 02:04:07 PM
I have three patches to fix some typos and to translate some German comments. I've divided to help, the makeobj.patch fixes some typos in the makeobj messages.

Edit: patches removed, all were committed in trunk.
Title: Re: German in the code
Post by: Dwachs on February 16, 2017, 06:53:47 PM
Please commit these patches :) Thanks!
Title: Re: German in the code
Post by: An_dz on February 18, 2017, 12:29:08 PM
I've translated what I could from platzsucher without messing with platzsucher_t, please review it's ok.

Edit: patch removed, updated version below
Title: Re: German in the code
Post by: prissi on February 18, 2017, 01:00:49 PM
neu_starten is rather restart

Also I would suggest beste_reihe into best_row, reihe into row and psuch1 into results_straight and psuch2 into results_rotated
Title: Re: German in the code
Post by: An_dz on February 18, 2017, 02:35:28 PM
Thanks, changed it.

Edit:
Now I've translated everything, including platzsucher_t and all derived classes. Please review everything is well translated. I've already tested if it compiles. And what's the best translation for spalten?
Title: Re: German in the code
Post by: An_dz on February 20, 2017, 12:45:05 PM
Just posting again as prissi and Dwachs might have not noticed my edit above ;D :P
Title: Re: German in the code
Post by: prissi on February 20, 2017, 01:03:05 PM
Reihe row
Spalte column

Just one last (easy) comment: Should this function not be rather a "finder"? In the comments in other sections I found more mentioning of wayfinder,  etc.

In any case, thank you.
Title: Re: German in the code
Post by: Dwachs on February 20, 2017, 07:11:23 PM
ist_randfeld -> is_boundary_place (rand = boundary, feld = place/tile/position/etc)
ist_feld_ok -> is_position_ok (checks a single tile, ist_platz_ok checks complete area of  b x h tiles)
strasse_bei -> is_road_at ?
Title: Re: German in the code
Post by: An_dz on February 20, 2017, 08:59:45 PM
ist_feld_ok -> is_tile_ok (checks one tile)
ist_platz_ok -> is_area_ok (checks area of tiles)
ist_randfeld -> is_boundary_tile

Took me quite a while to understand what ist_randfeld was doing, I'll add this comment above it to explain what it does:
Code: [Select]
/*
 * Checks if the tile is part of the building or if it's a boundary tile
 * @return false, when tile is part of the building
 * @return true, when tile is the boundary tile of the building
 */

strasse_bei -> is_road_at ?
Agree.
Title: Re: German in the code
Post by: Ters on February 21, 2017, 06:25:54 AM
strasse_bei -> is_road_at ?

If the context is that you have a road, and want to check if that road is at a particular location, that seems a good choice. If the context is that you have a tile, and want to know if it contains any road, I would have gone with has_road.
Title: Re: German in the code
Post by: An_dz on February 21, 2017, 12:17:02 PM
The context is the later. But I would agree if you would call this as tile->has_road() but as it's is_road_at(x, y) then I think the current is better.
Title: Re: German in the code
Post by: An_dz on February 24, 2017, 06:21:11 PM
@dwachs
I see you translated grundwasser as groundwater. I think it would be better as waterground.
Title: Re: German in the code
Post by: Dwachs on February 24, 2017, 06:23:55 PM
This does not seem to be an English word? I felt groundwater_level was too long. Feel free to change to something better :)
Title: Re: German in the code
Post by: An_dz on February 24, 2017, 06:59:14 PM
Maybe change to simply waterlevel, as I searched and groundwater is the water beneath the surface, like in aquifers.
Title: Re: German in the code
Post by: Ters on February 24, 2017, 08:24:26 PM
One might call it ocean or sea. Maybe sealevel, but that is more about the height than the actual surface, I think.
Title: Re: German in the code
Post by: An_dz on February 24, 2017, 09:03:28 PM
You can, but sea/ocean depends on your interpretation of what is sea/ocean. This level can be used for a 4x4 square full of water, but I wouldn't call that an ocean. ;)
Title: Re: German in the code
Post by: isidoro on February 25, 2017, 12:12:03 AM
Agree.  Sometimes precision isn't needed when there will be no doubt about what it means in the game.
Title: Re: German in the code
Post by: prissi on February 25, 2017, 11:16:01 AM
I though the ground water is called water table in English. Anyway, water_level should be very clear. Or maybe sea_level, because there are lakes above with the own water_level. Or submarine climate ...
Title: Re: German in the code
Post by: Ters on February 25, 2017, 11:39:42 AM
I think ground water and water table is like ocean and sea level.
Title: Re: German in the code
Post by: jamespetts on February 25, 2017, 12:28:43 PM
I think ground water and water table is like ocean and sea level.

Not necessarily: the water table is the depth of ground water, which might well be higher than sea level depending on local circumstances. Ground water is usually fresh water.
Title: Re: German in the code
Post by: Ters on February 25, 2017, 04:06:13 PM
Not necessarily: the water table is the depth of ground water, which might well be higher than sea level depending on local circumstances. Ground water is usually fresh water.

I wasn't comparing water table and sea level. I was comparing the comparisons.
Title: Re: German in the code
Post by: An_dz on March 02, 2017, 12:59:27 AM
So, everybody agrees with sea_level?



And I'm currently translating the last bits from the descriptor folder, I noticed a lot of incompatibilities among the files.

Some have member distribution_weight others have it called chance. Some have member cost, others call it price.

I think they should have the same name if they represent the same thing. And I also think the names should follow a closer relation to the dat parameters.

So what do you prefer?
cost vs. price
chance vs. distribution_weight
Title: Re: German in the code
Post by: jamespetts on March 02, 2017, 01:01:07 AM
I prefer "price" to "cost" and "chance" to "distribution_weight", as both are, in my view, clearer.
Title: Re: German in the code
Post by: DrSuperGood on March 02, 2017, 04:44:30 AM
Be aware that distribution weight and chance might be mechanically very different. A chance should be a probability, possibly in a fixed point form which represents how likely something will occur. A weight is an arbitrary number that larger numerically means higher likelihood of occurring. A weight only has meaning when inside a set of objects to select from, where as a probability has a meaning by itself. Probability is always normalized between 0.0 and 1.0 where as a weight can have an arbitrary scale. One can get a probability for a specific weight from a set of weights, but not from a weight alone.

For example in Simutrans...
Chance for passengers/mail to spawn from a specific building -> passenger/mail_weight of building inside appropriate building set
Chance for either passengers or mail to be generated -> passenger/mail probability (only 1 is declared as other is implicitly the not probability of that)
Title: Re: German in the code
Post by: prissi on March 02, 2017, 05:14:27 AM
Some objects/decsriptors have more than one randoms parameter. As such, chance without anything specifying is less clear than before. Apart from the iferences between weights and probailities ountlined above.

I agree that it should be maintenance_cost but price for buying.
Title: Re: German in the code
Post by: An_dz on March 02, 2017, 04:14:40 PM
Ok, so I'll change:
cost -> price
wt -> wtyp (to to be similar to styp & own_wtyp)
obsolete_date -> retire_date
chance -> distribution_weight

Also, I believe the version check should be standardised. Some check from 0 to n, others from n to 0.

As I don't believe the compiler moves the order of those checks, I think all checks should be from n to 0.

Edit:
laden_abschliessen was renamed to finish_loading as it's the last step after loading objects and so to check xrefs.
Title: Re: German in the code
Post by: jamespetts on April 12, 2017, 10:25:21 PM
I see that some splendid progress has been made on this of late, although I note that there is still a little work to do.

May I suggest the following furhter translations (all intended to be search/replace pairs, without "whole word only" unless with an asterisk)?

karte_t > world_t
world() > get_world()
welt > world

grund_t > ground_t
bd > gr *
ist_karten_boden > is_within_map
lookup_kartenboden > lookup_surface_tile
boden_ersetzen > replace_ground
wasser > water
ist_uebergang > is_transition

stadt > city

baum > tree

hausbauer > building_builder

get_weg_hang > get_way_slope
wegbauer > way_builder
weg > way
schiene > railway
strasse > road
kanal > canal
hat_wege > has_way

wegbauer > way_builder

warten_bis_weg_frei > wait_until_way_free

ribi > dirs

koord > world_coord
koord3d > world_coord3d
flughohe > altitude
hoehe > height

zeiger > ??? (cursor? pointer?)
bauigel > ??? (constructor? construction?)

vehikelbauer > vehicle_builder
fahrzeuge > vehicles

wolke > smoke
Title: Re: German in the code
Post by: An_dz on April 13, 2017, 03:55:16 AM
I don't see why koord should be world_coord I think coord is enough as it's obvious it's the coordinates on the world.
Title: Re: German in the code
Post by: Vladki on April 13, 2017, 06:17:14 AM
Wolke literally means cloud, but I've not seen any other clouds than smoke in the game. Just wondering if there is a feature that I don't know about...



Title: Re: German in the code
Post by: Leartin on April 13, 2017, 07:04:19 AM
Wolke literally means cloud, but I've not seen any other clouds than smoke in the game. Just wondering if there is a feature that I don't know about...
Aren't there clouds in p96c? :P

Without checking, I'd assume it's because smoke/Rauch is uncountable, while cloud/Wolke is countable. It's just linguistics, but it makes a lot more sense for a steam locomotive to spawn "a cloud" ever so often, rather than "a smoke". Or "Eine Wolke" rather than "Einen Rauch".
Title: Re: German in the code
Post by: prissi on April 13, 2017, 07:18:56 AM
There was smoke for synchronised (sync_step) and asynchronous (step) smoke in old games. Now they are all smoke.
Title: Re: German in the code
Post by: userfriendly on December 04, 2017, 10:20:44 PM
Translate karte_t to map_t. Proposed patch attached and a GitHub PR for reference: https://github.com/user-friendly/simutrans/pull/1
The patch is quite big, but there are no compiler errors (clang version 4.0.1-6).
Title: Re: German in the code
Post by: Ters on December 05, 2017, 06:58:06 AM
karte_t is supposed to become world_t, not map_t.
Title: Re: German in the code
Post by: Dwachs on December 05, 2017, 01:09:39 PM
karte_t is the universe: it not only contains the map, it manages all the objects in the gam, it runs the game loop, etc. So neither translation world_t or map_t is right imho.
Title: Re: German in the code
Post by: jamespetts on December 05, 2017, 02:43:39 PM
Is "world" really different from "universe" in this context?
Title: Re: German in the code
Post by: Ters on December 05, 2017, 05:54:26 PM
There might be multiple worlds in one universe. There can only be one world in karte_t.
Title: Re: German in the code
Post by: userfriendly on December 05, 2017, 05:58:44 PM
Ok guys, I'm gonna stay out of the discussion, because it doesn't really matter to me. Either will work, I just want to translate the source to English (not that I don't like German!).
I'm willing to work and this seems like it can be done relatively easy, so if you have a list of words that everybody came to a consensus on, I'll gladly work on translating these, providing one patch per word.
Title: Re: German in the code
Post by: Ters on December 05, 2017, 06:01:39 PM
The hardest problem in the field of computer science is what to call things.
Title: Re: German in the code
Post by: jamespetts on December 05, 2017, 06:40:06 PM
There might be multiple worlds in one universe. There can only be one world in karte_t.

But there are not multiple worlds in the Simutrans universe, hence asking whether the difference is significant in this context.

Edit: Also, universe_t would be a lot to have to type many times when writing code.
Title: Re: German in the code
Post by: Ters on December 05, 2017, 07:30:43 PM
But there are not multiple worlds in the Simutrans universe

So savegame_frame_t sees the Simutrans multiverse, then?
Title: Re: German in the code
Post by: jamespetts on December 05, 2017, 07:34:58 PM
So savegame_frame_t sees the Simutrans multiverse, then?

Possibly. I wonder how many multiverses that there are?

(But this is not quite the same, as there is only ever one karte_t object in existence at the same time. Indeed, I believe that it is now static).
Title: Re: German in the code
Post by: Ters on December 05, 2017, 09:04:19 PM
(But this is not quite the same, as there is only ever one karte_t object in existence at the same time. Indeed, I believe that it is now static).

It was turned from a global to a singleton, which is just putting fancy wrapping paper on it.
Title: Re: German in the code
Post by: jamespetts on December 05, 2017, 09:17:17 PM
It was turned from a global to a singleton, which is just putting fancy wrapping paper on it.

I like wrapping paper. Does it also have a bow?
Title: Re: German in the code
Post by: Ters on December 06, 2017, 06:52:12 AM
Apparently, yes.
Title: Re: German in the code
Post by: Leartin on December 06, 2017, 08:44:18 AM
Just call it "verse_t" - you wouldn't have to fight over whether it's multi- or uni-; it's short enough, and it sounds poetic :)
Title: Re: German in the code
Post by: prissi on December 06, 2017, 02:06:38 PM
Although my first though would be poetic. Also, since world is English, maybe rather focus on the real German words ...
Title: Re: German in the code
Post by: Ters on December 06, 2017, 05:57:08 PM
The files containing karte_t are already called simworld by the way.
Title: Re: German in the code
Post by: Dwachs on December 07, 2017, 10:15:52 AM
Then let us translate karte_t to world_t and move on.
Title: Re: German in the code
Post by: userfriendly on December 07, 2017, 04:23:17 PM
Translate karte_t to world_t. Proposed patch attached and a GitHub PR for reference: https://github.com/user-friendly/simutrans/pull/2
No compiler errors (clang version 4.0.1-6).
Title: Re: German in the code
Post by: ACarlotti on August 15, 2018, 02:32:01 PM
I've produced a series of patches to complete the translation of komp->comp and komponente->component (and fix a nearby typo). (This has been partly translated in Standard but completely translated in Extended.)

1. Fix comment typo
2. Translate komp->comp in documentation.
3. Translate gui_komponente.(c|hh)
4. Finish translating komp->comp
Title: Re: German in the code
Post by: prissi on August 26, 2018, 01:38:04 PM
Since there are some patches pending, this will be done when those have been incorporated, at least the big patch.
Title: Re: German in the code
Post by: ACarlotti on April 10, 2019, 12:49:11 AM
Would this now be an appropriate time for the komp->comp patches? (I have an updated version that reflects recent changes).

On a (semi-)related note, I've been comparing some of the translation changesets in Standard and Extended recently. The attached diff arose mostly from looking at the translation of 'spieler', and is made mostly of typo fixes and variable renames. These are drawn largely from changes in Extended, where the version in Extended seemed better. (Conversely, where the version in Standard is as good as Extended, I've copied the Standard version for Extended). Is there any reason not to incorporate these?
Title: Re: German in the code
Post by: prissi on April 10, 2019, 06:16:09 AM
This seems only comments and some underscore removal in names, so it makes sense to do this.