What is the best way to make sense of an applications code?

[Curious Gorge]

Hello again! I want to know what the best way to approach understanding how an application works is. I have a game that is highly moddable with Lua and I would actually like to do that. The problem is I don't know how to make sense of it all. There are maybe a hundred to 150 lua files to sift through.

Besides using the "find in files" feature in most scripting applications how else could I find out how everything or just a few pieces of it work? If I wanted to do just a few small mods what would be the best way to do that? Must I understand the entire picture or just select parts of it? This is something I have never done before. I hope this isn't a pointless question that can't be answered.

[mike_2000_17]

This is indeed something of a problem. It is always difficult to jump into a new and large code-base. You should concentrate on any available overview documentation (e.g., explaining how it works or is structured), tutorials (e.g., showing how to make mods), and reference documentation (e.g., class references).

If you need to really dig into the source code of the library / application, then you need to find a relevant starting point. This could be something that is similar to what you want to do or modify. When you find a decent starting point, just look it up and try to understand what it does and how it works, and work your way out from there, by looking up related code (e.g., that is called within that code you are looking at, etc.). The "find in files" is definitely a central tool when exploring a code-base because it gives you an instant snapshot of where certain things are used and declared. For example, if you want to modify the behavior of class A, then there is a good chance that you will want to look at all the places where class A is used so that you can assess if your modified version will work or if you need to modify other things.

There is no doubt that doing this is hard and takes a lot of patience. I've done this several times with different code bases (some small ( < 50,000 LOCs ), some big ( > 1,000,000 LOCs )), and it's always a tedious process, especially if documentation is lacking (which it very often is).

[Curious Gorge]

Ah, what you've told me is exactly what I was thinking I had to do. Thank you!

Yes its funny that coding applications never provide enough documentation for modders, maintainers, or even open source projects communities that want to use it to actually do that. I don't understand it, maybe its a business thing? Time is money and all that? Maybe its an ego thing. Who knows?

[L7Sqr]

Probably more of a boredome thing. Documentation is boring. Documentation maintenance is even worse.

Part of the thrill of programming is getting something to work. Once it works there are other challenges like extending what you have just created; supporting others' interest in your technology; refactoring out the nasty parts. There is little room in there to sit back, write prose to explain what is happening and keep that current with the evolving mass you have on your hands.

If you are lucky, you get someone who writes comments amenable to an auto-documenter tool such as doxygen or similar. Even then it is often just code - but web-browseable code is at least better than flat files.

[mike_2000_17]

I agree. The reason documentation is often very poor is due to the boredom factor. Writing documentation like overviews, examples and tutorials is just extremely boring, and nobody wants to do it. At least, that's the only reason why my library is not very well documented.

At least with the fairly well-established practice of interface commenting and the automatic generation of reference documentation (e.g., doxygen), there is at least a decent start, which is better than nothing, but not that easy to navigate either.

A lot of what actually makes a code-base easy to understand is when it relies on good and well-established coding practices. When there are no awkward design choices or hidden surprises in the behavior, it's a lot easier to deal with. These practices include things like flat class hierarchies, value-semantics, hidden polymorphism (i.e., non-virtual interfaces), no side-effects within functions, const-correctness, just to name a few.

[Curious Gorge]

Oh yes, I forgot to mention that too. I know documentation is pretty friggin' dry material to read, I cannot imagine what its like to write it. I would see it was a means to an end though. If you have an open source project why wouldn't you take the time to make sure it were well documented even if it very boring? That defeats the purpose of your project because without it your project is almost pointless because nobody has the time or inclination to learn to use its codebase.

[L7Sqr]

Unfortunately that is not universally true. Consider a tool such as ns-3. There is some documentation here and there but for the deeper uses of the tool there is only doxygen. The codebase is large, used often, and constantly in flux so by the time you get to understand what is going on you dont need the documentation anymore (and are likely behind schedule so not inclined to write any).
What you end up with is newsgroups and mailing lists as the goto reference for how to do some more esoteric things. Otherwise it is basically 'use the source, Luke'