News:

Simutrans Tools
Know our tools that can help you to create add-ons, install and customize Simutrans.

German in the code

Started by felo, March 10, 2010, 05:48:22 PM

Previous topic - Next topic

0 Members and 1 Guest are viewing this topic.

prissi

The date could be gotten anyway from SVN/git ...

VS

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 :)

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

eipi

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.

Dwachs

Quote from: eipi on July 08, 2012, 12:53:32 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.
Parsley, sage, rosemary, and maggikraut.

eipi

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.

An_dz

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.

kierongreen

Nice work - only reason I'm not going to patch this just now is that there's the GUI Theme Patch being developed at the moment and I fear this would probably conflict in a few places...

An_dz

No conflicts here, and it might help Max, he doesn't read German. Not that I know much :p.

An_dz

Patches for docs, display and vehicle folders.

Dwachs

#149
Quote from: An_dz on September 01, 2013, 10:58:48 PM
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:
Quote from: An_dz on September 03, 2013, 05:13:16 PM
Patches for docs, display and vehicle folders.
Now in r6672 & 6673.
Parsley, sage, rosemary, and maggikraut.

An_dz

Quote from: Dwachs on September 04, 2013, 07:47:23 AM
Thank you! In r 6671. You fixed some prety epic typos.
*pretty ;D

Quote from: Dwachs on September 04, 2013, 07:47:23 AMNow in r6672 & r6673
I found I wrongly translated one string in vehikel, will be fixed on next set of patches.

Dwachs

The best typo was: cooledcted -> collected. And not to forget: crossong, where somebody suggested cross-song :P
Parsley, sage, rosemary, and maggikraut.

whoami

Ah yes, the well known cross-singing!
"Let's do the time warp agaaaaain..."

An_dz

Quote from: 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
Haha. Yeah, I did some shits.
At least I'm forcing you to translate, and clean, the comments. :D

Max-Max

@An_dz
Thank you for the translations :thumbsup: I do appreciate it!

@kierongreen
Quote from: 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 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.
- My code doesn't have bugs. It develops random features...

eipi

More translations on the way... :)

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

Patch against r6720.

kierongreen

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.

Ters

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.)

Markohs

Agree, lots of deep changes in the code means we can mess with it even more. ;)

eipi

Quote from: 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.

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.

prissi

I would also suggest state.

Why were correct comments remove from the cc files? (Most were trivial, but still ... )

Markohs

I think he moved the comments to the .h, that's the place they should be

Ters

Quote from: 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

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.

Markohs

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? :)

Ters

Quote from: 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? :)

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.)

prissi

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.

Markohs

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.

Ters

Quote from: Markohs on September 18, 2013, 11:26:44 PM
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.

kierongreen

Summary in the .h any detailed comments in .cc would be my suggestion...

Markohs

#169
 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

prissi

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.)

Markohs

Quote from: 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).

Well, we agree here. :)

But anyway a oneliner is better than nothing at all.

Quote from: prissi on September 19, 2013, 10:27:00 AM
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

Quote from: prissi on September 19, 2013, 10:27:00 AM
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).

Quote from: prissi on September 19, 2013, 10:27:00 AM
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. :)

Quote from: prissi on September 19, 2013, 10:27:00 AM
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.

Quote from: prissi on September 19, 2013, 10:27:00 AM
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.

Quote from: prissi on September 19, 2013, 10:27:00 AM
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.

Quote from: prissi on September 19, 2013, 10:27:00 AM
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

Quote from: prissi on September 19, 2013, 10:27:00 AM
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. ;)

prissi

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 ...

Markohs

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 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. :)

kierongreen

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).