An interesting reddit comment on code structure

[raevol]

I made a little attempt to do some code documentation a bit ago. I have to say that the results were incredibly discouraging.

Maybe I'll make a thread about that or post in one of our documentation threads. If I can get up the motivation. Definitely fighting against the tide here...

[Naugrim]

I made a little attempt to do some code documentation a bit ago. I have to say that the results were incredibly discouraging.

Maybe I'll make a thread about that or post in one of our documentation threads. If I can get up the motivation. Definitely fighting against the tide here...

Please, do write about that! If only to identify the pain points, that also very helpful.

[raevol]

I guess I'll just post here.

So this is just my opinion and experience. I'm not a seasoned C++ coder, I am a student and have never contributed code to a project as large as OpenMW. The biggest thing I have ever done aside from homework assignments is to write a 2d RPG engine in LUA.

That said, here's what happened. I made a fork of OpenMW to try to start reading the code. The first thing I noticed is there is absolutely no "point of entry" for someone getting started with the code. There's no documentation on the wiki, in the code docs, or even in a readme file to orient a beginner. So I spent a ton of time digging through the folders trying to figure out where the code even existed. I finally found it, it's in the apps/openmw folder. Of course this is a logical place for it, but for a newcomer, it takes some digging.

Then I tried to trace the execution of the code to something that looked like an "update" loop in the traditional load-update-draw model that most games have. I think I did manage to find the int main() function for the whole engine, but following it from there was a complete mess to my unskilled efforts. I managed to find functions that don't even exist in other source files, such as the engine.reset() call.

From there, I decided that maybe a good place to start would be to document the directory structure of the code, even if most of it was // TODO: wtf is this directory? But I'm at a complete loss for how to create a "page" in our documentation to hold that kind of information. So I gave up.

Again, if I was a "real" programmer, maybe it wouldn't have been so hard. I'm sure our devs who are doing real work on this project are going to read this and laugh at how lost I was. But if you want to know what a nooby C++ programmer's attempt at reading out code was like, there you go.

[Capostrophic]

If you ever want help with documenting the source, I'll love to assist.

[raevol]

If you ever want help with documenting the source, I'll love to assist.

Yes, we would love help!

[scrawl]

I think the best place to start would be improving our Doxygen documentation.

On that note, I have set up hosting on github pages which is automatically updated by travis-ci on each push to the doxygen branch.

Then I tried to trace the execution of the code to something that looked like an "update" loop in the traditional load-update-draw model that most games have. I think I did manage to find the int main() function for the whole engine, but following it from there was a complete mess to my unskilled efforts. I managed to find functions that don't even exist in other source files, such as the engine.reset() call.

In this case, the reset() comes from std::auto_ptr.

I recommend using an IDE (e.g. QtCreator) that lets you Ctrl+Click on a symbol to find where that symbol originates. Makes looking through the code a breeze.

From there, I decided that maybe a good place to start would be to document the directory structure of the code

How about https://wiki.openmw.org/index.php?title=Architecture ?

[raevol]

So now we have three different places we are keeping documentation? Correct me if I'm wrong.

I recommend using an IDE (e.g. QtCreator) that lets you Ctrl+Click on a symbol to find where that symbol originates. Makes looking through the code a breeze.

Is this just "how it's done" in the programmer world? Again, I haven't been part of big projects, so I am used to seeing lots of comments written directly into the code to explain things like where that call would come from. Am I the only person who's lost over this, because I don't use an IDE?

[psi29a]

It is very hard to comment on code if you are not a programmer yourself. It is however VERY useful to have an IDE like QTCreator, CLion, code::blocks or even Eclipse (and others) which makes following code so much easier.

You are reading through the code and see that your function calls another function, you can click-through (like scrawl said) the function name and it takes you to that function name. We've come to rely on this quite a bit.

[ezze]

I think comments in the code to tell what lines do are overrated. If you need to comment the code to make it clear what is does, it's better to rewrite it more clearly. Of course if it is not possible (e.g., it's a complex optimization because the compiler just don't get it) then a comment is fine. But in general, comments are risky: our brain reads the english before the code and in case of incongruences it's much easier missing bugs.

What is really underrated, are the high level comments. An high level description of what every file contains in the beginning, or description of what directories contain, what a class is there for... and similar high level description would make life of new developers much more easy. Since one have little-to-no idea where to look for to do what they need in the beginning.

[raevol]

What is really underrated, are the high level comments. An high level description of what every file contains in the beginning, or description of what directories contain, what a class is there for... and similar high level description would make life of new developers much more easy. Since one have little-to-no idea where to look for to do what they need in the beginning.

I definitely agree with this.