How to understand the source code of OpenTTD?

[ANTIKLAN]

Hello!
I know how to program in C ++ and I have a desire to change or add some features to the game. I downloaded the source code of the game. And horror of horrors! I can not understand where I change or add features I needed. Tell me how to understand the source code OpenTTD programmer who has not participated in the project from the very beginning?

[Alberth]

Understanding a large program (300K lines) not written by you is a skill you have to develop as well. It's very different from navigating in your own code, as you know that inside out. It's also humbling, this is how other people see your code. The authors are as smart as sane as you, so it's reasonable to assume they try to write equally clear code as you would do.

Enough philosophy, some more practical hints and tips.

The first thing to do is not to panic. 300K lines is a book of about 6000 pages, it takes a while to grasp that. Secondly, look at the file names. You'll notice patterns *_cmd.cpp are command files, *_gui.cpp are about (you guessed it), gui windows. Also there are groups of related files newgrf* does things with newgrfs, and so on.
Similarly, directory names have meaning too, "lang" has languages, "saveload" handles save and load, and so on.

Thirdly, learn about grep. It's a file search tool. There is also ag, ack, and a few others. Some IDEs have it too. Basically, they look for a name or pattern in the file, and output a list of matches. If you want to find a certain topic, finding it by using its name often works (and sometimes it doesn't as it has a slightly different name).

Fourth, another search strategy is to find and use related things. If you want to know the price of a bridge, but you can't find it, look for the bridge gui instead. It shows the price of a bridge, so it must have code that computes the price right?

Once you get the hang of this, you'll soon find a function that is at least related. Then start reading code, skip most of the details, just get a global picture. You'll find interesting other function names, and you can read those functions too, building yourself a picture of what the code does.


From there you can start thinking on what changes to make to get what you desire.


Last but not least, join the IRC channel, people there can likely point you in the right direction much faster than a forum discussion.

[ANTIKLAN]

Understanding a large program (300K lines) not written by you is a skill you have to develop as well. It's very different from navigating in your own code, as you know that inside out. It's also humbling, this is how other people see your code. The authors are as smart as sane as you, so it's reasonable to assume they try to write equally clear code as you would do.

Enough philosophy, some more practical hints and tips.

The first thing to do is not to panic. 300K lines is a book of about 6000 pages, it takes a while to grasp that. Secondly, look at the file names. You'll notice patterns *_cmd.cpp are command files, *_gui.cpp are about (you guessed it), gui windows. Also there are groups of related files newgrf* does things with newgrfs, and so on.
Similarly, directory names have meaning too, "lang" has languages, "saveload" handles save and load, and so on.

Thirdly, learn about grep. It's a file search tool. There is also ag, ack, and a few others. Some IDEs have it too. Basically, they look for a name or pattern in the file, and output a list of matches. If you want to find a certain topic, finding it by using its name often works (and sometimes it doesn't as it has a slightly different name).

Fourth, another search strategy is to find and use related things. If you want to know the price of a bridge, but you can't find it, look for the bridge gui instead. It shows the price of a bridge, so it must have code that computes the price right?

Once you get the hang of this, you'll soon find a function that is at least related. Then start reading code, skip most of the details, just get a global picture. You'll find interesting other function names, and you can read those functions too, building yourself a picture of what the code does.


From there you can start thinking on what changes to make to get what you desire.


Last but not least, join the IRC channel, people there can likely point you in the right direction much faster than a forum discussion.

Thank you for your response! If possible let's look at an example. I have an idea on how to add more features that will automatically fill in catastrophes lost vehicles. I tried to search for the keyword crash only to find that something to do with CrashLog and as I understand it is connected only with information about the incident. If you can let us analyze step by step as I enter the code responsible for handling crashes.
P.S. As I understand the game written in object-oriented style. How much intertwined classes and whether changes will result in the same place to the abandonment of the game or the game completely?

[Alberth]

Thank you for your response! If possible let's look at an example. I have an idea on how to add more features that will automatically fill in catastrophes lost vehicles.

Wouldn't it be simpler to just disable crashing?

The game play reason for having crashes is to teach the player not to be careless. If you automate that away, you're defeating its purpose. It is much simpler to just remove the feature in that case.

I tried to search for the keyword crash only to find that something to do with CrashLog and as I understand it is connected only with information about the incident. If you can let us analyze step by step as I enter the code responsible for handling crashes.

So you learned "crash" is the wrong magic word. Did you try other words, like "accident", "died" (this will likely give you hits on strings, which have a name you can look up in code), "Delete" (probably useful in combination with "Vehicle"), etc

The point is, the code is not written following your logic. You may call it "crash", other persons may use different names or wording of things and events, be creative, if one thing fails, try another thing.

Did you try finding the code that deals with vehicles? Did you find any function that sounds like a crash-related thing? Did you try finding the news message reporting such a crash?

Don't focus on one small item. Throw out a wide net at first. That works better if you don't exactly know what you will find.

P.S. As I understand the game written in object-oriented

It's written in object-oriented style?
Well, yeah, some parts are, There are also parts where the concept 'class' has not been invented yet.
300K lines of code doesn't upgrade from C to nowadays C++ in the blink of an eye. Some code has not been touched in eons.

How much intertwined classes and whether changes will result in the same place to the abandonment of the game or the game completely?

Things are pretty much nicely layered, although it's not something you can easily see. A lot is streamlined to get maximum throughput. Most of the complexity comes from multi-player, decisions must be made on all participating machines at the same time.

[ANTIKLAN]

Thank you for your response! If possible let's look at an example. I have an idea on how to add more features that will automatically fill in catastrophes lost vehicles.

Wouldn't it be simpler to just disable crashing?

The game play reason for having crashes is to teach the player not to be careless. If you automate that away, you're defeating its purpose. It is much simpler to just remove the feature in that case.

I tried to search for the keyword crash only to find that something to do with CrashLog and as I understand it is connected only with information about the incident. If you can let us analyze step by step as I enter the code responsible for handling crashes.

So you learned "crash" is the wrong magic word. Did you try other words, like "accident", "died" (this will likely give you hits on strings, which have a name you can look up in code), "Delete" (probably useful in combination with "Vehicle"), etc

The point is, the code is not written following your logic. You may call it "crash", other persons may use different names or wording of things and events, be creative, if one thing fails, try another thing.

Did you try finding the code that deals with vehicles? Did you find any function that sounds like a crash-related thing? Did you try finding the news message reporting such a crash?

Don't focus on one small item. Throw out a wide net at first. That works better if you don't exactly know what you will find.

P.S. As I understand the game written in object-oriented

It's written in object-oriented style?
Well, yeah, some parts are, There are also parts where the concept 'class' has not been invented yet.
300K lines of code doesn't upgrade from C to nowadays C++ in the blink of an eye. Some code has not been touched in eons.

How much intertwined classes and whether changes will result in the same place to the abandonment of the game or the game completely?

Things are pretty much nicely layered, although it's not something you can easily see. A lot is streamlined to get maximum throughput. Most of the complexity comes from multi-player, decisions must be made on all participating machines at the same time.

Thank you for your response! Today I will try to find other keywords, or other parts associated with disasters. On the results reported in this thread.